Integrar a o Microsoft Entra ID ao Serviço de Kubernetes do Azure (AKS) usando a CLI do Azure (herdada)

  • Artigo

Aviso

O recurso descrito nesse documento, a Integração do Microosft Entra (herdado), foi preterido em 1º de junho de 2023. No momento, não é possível criar novos clusters com a Integração do Microsoft Entra (herdado).

O AKS tem uma nova experiência aprimorada do Microsoft Entra ID gerenciada pelo AKS que não exige que você gerencie aplicativos de servidor ou de cliente. Se você deseja fazer a migração, siga as instruções descritas aqui.

O Serviço de Kubernetes do Azure (AKS) pode ser configurado para usar o Microsoft Entra ID para autenticação de usuário. Nessa configuração, é possível fazer logon em um cluster do AKS usando o token de autenticação do Microsoft Entra. Os operadores do cluster também podem configurar o RBAC do Kubernetes (controle de acesso baseado em função do Kubernetes) com base na identidade do usuário ou na associação a um grupo de diretórios.

Esse artigo mostra como criar os componentes do Microsoft Entra necessários e implantar um cluster habilitado para o Microsoft Entra ID e criar uma função básica do Kubernetes no cluster do AKS.

Limitações

  • O Microsoft Entra ID só pode ser habilitado no cluster habilitado para RBAC do Kubernetes.
  • A integração herdada do Microsoft Entra só pode ser habilitada durante a criação do cluster.

Antes de começar

Você precisará da CLI do Azure versão 2.0.61 ou posterior instalada e configurada. Execute az --version para encontrar a versão. Se você precisa instalar ou atualizar, consulte Instalar a CLI do Azure.

Acesse https://shell.azure.com para abrir o Cloud Shell no navegador.

Para fins de consistência e para ajudar a executar os comandos deste artigo, crie uma variável para o nome do cluster do AKS desejado. O seguinte exemplo usa o nome myakscluster:

aksname="myakscluster"

Visão geral da autenticação do Microsoft Entra

A autenticação do Microsoft Entra é fornecida aos clusters do AKS com OpenID Connect. O OpenID Connect é uma camada de identidade compilada sobre o protocolo OAuth 2.0. Para obter mais informações sobre o OpenID Connect, consulte a documentação do Open ID Connect.

No cluster do Kubernetes, a Autenticação de Token do Webhook é usada para verificar os tokens de autenticação. A autenticação de token do Webhook é configurada e gerenciada como parte do cluster AKS. Mais informações sobre autenticação de token do Webhook podem ser encontradas na documentação de autenticação do webhook.

Observação

Ao configurar o Microsoft Entra ID para autenticação do AKS, dois aplicativos do Microsoft Entra são configurados. Essa operação deve ser concluída por um administrador de locatário do Azure.

Criar componente do servidor do Microsoft Entra

Para a integração ao AKS, você criará e usará um aplicativo do Microsoft Entra que funciona como um ponto de extremidade para as solicitações de identidade. O primeiro aplicativo do Microsoft Entra de que você precisa obtém a associação de grupo do Microsoft Entra para um usuário.

Crie o componente do aplicativo para servidores usando o comando az ad app create e atualize as declarações de associação a um grupo usando o comando az ad app update. O exemplo a seguir usa a variável aksname definida na seção Antes de começar e cria uma variável

# Create the Azure AD application
serverApplicationId=$(az ad app create \
    --display-name "${aksname}Server" \
    --identifier-uris "https://${aksname}Server" \
    --query appId -o tsv)

# Update the application group membership claims
az ad app update --id $serverApplicationId --set groupMembershipClaims=All

Agora, crie uma entidade de serviço para o aplicativo de servidor usando o comando az ad sp create. Essa entidade de serviço é usada para se autenticar na plataforma Azure. Em seguida, obtenha o segredo da entidade de serviço usando o comando az ad sp credential reset e o atribua à variável chamada serverApplicationSecret para uso em uma das seguintes etapas:

# Create a service principal for the Azure AD application
az ad sp create --id $serverApplicationId

# Get the service principal secret
serverApplicationSecret=$(az ad sp credential reset \
    --name $serverApplicationId \
    --credential-description "AKSPassword" \
    --query password -o tsv)

A entidade de serviço do Microsoft Entra precisa ter permissões para executar as seguintes ações:

  • Ler dados do diretório
  • Entrada e leitura de perfil do usuário

Atribua essas permissões usando o comando az ad app permission add:

az ad app permission add \
    --id $serverApplicationId \
    --api 00000003-0000-0000-c000-000000000000 \
    --api-permissions e1fe6dd8-ba31-4d61-89e7-88639da4683d=Scope 06da0dbc-49e2-44d2-8312-53f166ab848a=Scope 7ab1d382-f21e-4acd-a863-ba3e13f7da61=Role

Por fim, conceda as permissões atribuídas na etapa anterior ao aplicativo para servidores usando o comando az ad app permission grant. Essa etapa falhará se a conta atual não for um administrador do locatário. Você também precisa adicionar permissões para o aplicativo do Microsoft Entra solicitar informações que, de outra forma, podem exigir consentimento administrativo usando az ad app permission admin-consent:

az ad app permission grant --id $serverApplicationId --api 00000003-0000-0000-c000-000000000000
az ad app permission admin-consent --id  $serverApplicationId

Criar componente de cliente do Microsoft Entra

O segundo aplicativo do Microsoft Entra é usado quando um usuário faz logon no cluster do AKS com a CLI do Kubernetes (kubectl). Esse aplicativo cliente usa a solicitação de autenticação do usuário e verifica as credenciais e as permissões dele. Crie o aplicativo do Microsoft Entra para o componente de cliente usando o comando az ad app create:

clientApplicationId=$(az ad app create \
    --display-name "${aksname}Client" \
    --native-app \
    --reply-urls "https://${aksname}Client" \
    --query appId -o tsv)

Crie uma entidade de serviço para o aplicativo cliente usando o comando az ad sp create:

az ad sp create --id $clientApplicationId

Obtenha a ID do OAuth2 para o aplicativo de servidor a fim de permitir o fluxo de autenticação entre os dois componentes de aplicativo usando o comando az ad app show. Essa ID do OAuth2 será usada na próxima etapa.

oAuthPermissionId=$(az ad app show --id $serverApplicationId --query "oauth2Permissions[0].id" -o tsv)

Adicione as permissões ao aplicativo cliente e aos componentes do aplicativo para servidores para usar o fluxo de comunicação do OAuth2 usando o comando az ad app permission add. Em seguida, conceda permissões para o aplicativo cliente se comunicar com o aplicativo para servidores usando o comando az ad app permission grant:

az ad app permission add --id $clientApplicationId --api $serverApplicationId --api-permissions ${oAuthPermissionId}=Scope
az ad app permission grant --id $clientApplicationId --api $serverApplicationId

Implantar o cluster

Com os dois aplicativos do Microsoft Entra criados, agora, crie o cluster do AKS em si. Primeiro, crie um grupo de recursos usando o comando az group create. O seguinte exemplo cria o grupo de recursos na região EastUS:

Crie um grupo de recursos para o cluster:

az group create --name myResourceGroup --location EastUS

Obtenha a ID de locatário da sua assinatura do Azure usando o comando az account show. Depois, crie o cluster do AKS usando o comando az aks create. O comando usado para criar o cluster do AKS fornece as IDs do aplicativo cliente e do servidor, o segredo da entidade de serviço do aplicativo para servidores e a ID de locatário:

tenantId=$(az account show --query tenantId -o tsv)

az aks create \
    --resource-group myResourceGroup \
    --name $aksname \
    --node-count 1 \
    --generate-ssh-keys \
    --aad-server-app-id $serverApplicationId \
    --aad-server-app-secret $serverApplicationSecret \
    --aad-client-app-id $clientApplicationId \
    --aad-tenant-id $tenantId

Por fim, obtenha as credenciais de administrador do cluster usando o comando az aks get-credentials. Em uma das etapas a seguir, você obterá as credenciais de cluster do usuário normal para ver o fluxo de autenticação do Microsoft Entra em ação.

az aks get-credentials --resource-group myResourceGroup --name $aksname --admin

Criar uma associação do RBAC do Kubernetes

Antes que uma conta do Microsoft Entra possa ser usada com o cluster do AKS, uma associação de função ou uma associação de função de cluster precisa ser criada. Funções definem as permissões a serem concedidas e ligações as aplicam aos usuários desejados. Essas atribuições podem ser aplicadas a um determinado namespace ou em todo o cluster. Para obter mais informações, confira Como usar a autorização do RBAC do Kubernetes.

Obtenha o nome UPN do usuário conectado no momento usando o comando az ad signed-in-user show. Essa conta de usuário está habilitada para integração do Microsoft Entra na próxima etapa.

az ad signed-in-user show --query userPrincipalName -o tsv

Importante

Se o usuário para o qual você concedeu a associação do RBAC do Kubernetes estiver no mesmo locatário do Microsoft Entra, atribua permissões com base no userPrincipalName. Se o usuário estiver em outro locatário do Microsoft Entra, consulte e use a propriedade objectId.

Crie um manifesto YAML chamado basic-azure-ad-binding.yaml e cole o conteúdo a seguir. Na última linha, substitua userPrincipalName_or_objectId pela saída da ID do objeto ou da UPN do comando anterior:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: contoso-cluster-admins
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: cluster-admin
subjects:
- apiGroup: rbac.authorization.k8s.io
  kind: User
  name: userPrincipalName_or_objectId

Crie a ClusterRoleBinding usando o comando kubectl apply e especifique o nome de arquivo do manifesto YAML:

kubectl apply -f basic-azure-ad-binding.yaml

Acessar o cluster com o Microsoft Entra ID

Agora, vamos testar a integração da autenticação do Microsoft Entra para o cluster do AKS. Defina o contexto de configuração kubectl para usar credenciais do usuário normal. Esse contexto transmite todas as solicitações de autenticação por meio do Microsoft Entra.

az aks get-credentials --resource-group myResourceGroup --name $aksname --overwrite-existing

Agora, use o comando kubectl get pods para ver os pods em todos os namespaces:

kubectl get pods --all-namespaces

Você receberá um prompt de entrada para se autenticar usando as credenciais do Microsoft Entra por meio de um navegador da Web. Depois que você se autenticar com êxito, o comando kubectl exibirá os pods no cluster do AKS, conforme mostrado na seguinte saída de exemplo:

kubectl get pods --all-namespaces

To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code BYMK7UXVD to authenticate.

NAMESPACE     NAME                                    READY   STATUS    RESTARTS   AGE
kube-system   coredns-754f947b4-2v75r                 1/1     Running   0          23h
kube-system   coredns-754f947b4-tghwh                 1/1     Running   0          23h
kube-system   coredns-autoscaler-6fcdb7d64-4wkvp      1/1     Running   0          23h
kube-system   heapster-5fb7488d97-t5wzk               2/2     Running   0          23h
kube-system   kube-proxy-2nd5m                        1/1     Running   0          23h
kube-system   kube-svc-redirect-swp9r                 2/2     Running   0          23h
kube-system   kubernetes-dashboard-847bb4ddc6-trt7m   1/1     Running   0          23h
kube-system   metrics-server-7b97f9cd9-btxzz          1/1     Running   0          23h
kube-system   tunnelfront-6ff887cffb-xkfmq            1/1     Running   0          23h

O token de autenticação recebido para kubectl é armazenado em cache. Você só receberá um aviso novamente para entrada quando o token tiver expirado ou o arquivo de configuração do Kubernetes for recriado.

Se você receber uma mensagem de erro de autorização depois de entrar com êxito usando um navegador da Web como na seguinte saída de exemplo, verifique os seguintes problemas possíveis:

error: You must be logged in to the server (Unauthorized)
  • Você definiu a ID do objeto ou o UPN apropriado, dependendo se a conta de usuário está ou não no mesmo locatário do Microsoft Entra.
  • O usuário não é um membro de mais de 200 grupos.
  • O segredo definido no registro de aplicativo para o servidor corresponde ao valor configurado por meio de --aad-server-app-secret
  • Confirme se apenas uma versão do kubectl está instalada em seu computador por vez. As versões conflitantes podem causar problemas durante a autorização. Para instalar a versão mais recente, use: az aks install-cli.

Perguntas frequentes sobre a migração da Integração do Microsoft Entra para o Microsoft Entra ID gerenciado pelo AKS

1. Qual é o plano de migração?

A Integração do Microsoft Entra (herdada) será preterida em 1º de junho de 2023. Após essa data, você não poderá criar novos clusters com o Microsoft Entra ID (herdado). Migraremos todos os clusters do AKS da Integração do Microsoft Entra (herdado) para a o Microsoft Entra ID gerenciado pelo AKS automaticamente a partir de 1º de agosto de 2023. Enviamos emails de notificação para administradores de assinatura afetados quinzenalmente para lembrá-los da migração.

2. O que acontecerá se eu não realizar nenhuma ação?

Seus clusters do AKS da Integração do Microsoft Entra (herdado) continuarão funcionando após 1º de junho de 2023. Migraremos automaticamente seus clusters para o Microsoft Entra ID gerenciado pelo AKS a partir de 1º de agosto de 2023. Pode ocorrer tempo de inatividade do servidor de API durante a migração.

O conteúdo do kubeconfig é alterado após a migração. Você precisa mesclar as novas credenciais no arquivo kubeconfig usando az aks get-credentials --resource-group <AKS resource group name> --name <AKS cluster name>.

Recomendamos atualizar o cluster do AKS para o Microsoft Entra ID gerenciado pelo AKS manualmente antes de 1º de agosto. Dessa forma, você pode gerenciar o tempo de inatividade fora do horário comercial, quando for mais conveniente.

3. Por que ainda recebo o email de notificação após a migração manual?

Leva vários dias para o email ser enviado. Se o cluster não tiver sido migrado antes de iniciarmos o processo de envio de email, você ainda poderá receber uma notificação.

4. Como posso verificar se meu cluster foi migrado para o Microsoft Entra ID gerenciado pelo AKS?

Confirme se o cluster do AKS foi migrado para o Microsoft Entra ID gerenciado pelo AKS usando o comando az aks show.

az aks show -g <RGName> -n <ClusterName>  --query "aadProfile"

Se o cluster estiver usando o Microsoft Entra ID gerenciado pelo AKS, a saída mostra que managed é true. Por exemplo:

    {
      "adminGroupObjectIDs": [
        "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
      ],
      "adminUsers": null,
      "clientAppId": null,
      "enableAzureRbac": null,
      "managed": true,
      "serverAppId": null,
      "serverAppSecret": null,
      "tenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    }

Próximas etapas

Para obter o script completo que contém os comandos mostrados nesse artigo, consulte o [Script de integração do Microsoft Entra no repositório de exemplos do AKS][script-completo].

Para usar os usuários e os grupos do Microsoft Entra para controlar o acesso aos recursos de cluster, consulte Controlar o acesso aos recursos de cluster usando o controle de acesso baseado em função do Kubernetes e as identidades do Microsoft Entra no AKS.

Para obter mais informações sobre como proteger clusters do Kubernetes, confira Opções de acesso e identidade do AKS.

Para obter as melhores práticas sobre identidade e controle de recursos, confira Melhores práticas para autenticação e autorização no AKS.