Integrar o Microsoft Entra ID com o Serviço Kubernetes do Azure (AKS) usando a CLI do Azure (legado)

  • Artigo

Aviso

O recurso descrito neste documento, Microsoft Entra Integration (legado) foi preterido em 1º de junho de 2023. No momento, nenhum novo cluster pode ser criado com o Microsoft Entra Integration (legado).

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

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

Este artigo mostra como criar os componentes necessários do Microsoft Entra e, em seguida, implantar um cluster habilitado para ID do Microsoft Entra e criar uma função básica do Kubernetes no cluster 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ê precisa da CLI do Azure versão 2.0.61 ou posterior instalada e configurada. Executar az --version para localizar a versão. Se precisar de instalar ou atualizar, veja Install Azure CLI (Instalar o Azure CLI).

Vá para https://shell.azure.com abrir o Cloud Shell no seu navegador.

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

aksname="myakscluster"

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

A autenticação do Microsoft Entra é fornecida para clusters AKS com OpenID Connect. OpenID Connect é uma camada de identidade construída sobre o protocolo OAuth 2.0. Para obter mais informações sobre o OpenID Connect, consulte a documentação do OpenID Connect.

De dentro do cluster Kubernetes, a Autenticação de Token Webhook é usada para verificar tokens de autenticação. A autenticação do token Webhook é configurada e gerenciada como parte do cluster AKS. Para obter mais informações sobre a autenticação de token Webhook, consulte a documentação de autenticação de webhook.

Nota

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

Criar componente de servidor Microsoft Entra

Para integrar com o AKS, você cria e usa um aplicativo Microsoft Entra que atua como um ponto de extremidade para as solicitações de identidade. O primeiro aplicativo Microsoft Entra que você precisa obtém a associação de grupo do Microsoft Entra para um usuário.

Crie o componente de aplicativo de servidor usando o comando az ad app create e, em seguida, atualize as declarações de associação ao 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 autenticar-se dentro da plataforma Azure. Em seguida, obtenha o segredo da entidade de serviço usando o comando az ad sp credential reset e 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 de permissões para executar as seguintes ações:

  • Ler dados do diretório
  • Iniciar sessão e ler o perfil de utilizador

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

Finalmente, conceda as permissões atribuídas na etapa anterior para o aplicativo de servidor usando o comando az ad app permission grant . Esta etapa falhará se a conta atual não for um administrador de locatário. Você também precisa adicionar permissões para o aplicativo Microsoft Entra solicitar informações que, de outra forma, poderiam exigir consentimento administrativo usando a permissão do aplicativo az ad 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 Microsoft Entra é usado quando um usuário faz logon no cluster AKS com a CLI do Kubernetes (kubectl). Este aplicativo cliente recebe a solicitação de autenticação do usuário e verifica suas credenciais e permissões. Crie o aplicativo Microsoft Entra para o componente 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 oAuth2 para o aplicativo de servidor para permitir o fluxo de autenticação entre os dois componentes do aplicativo usando o comando az ad app show . Este ID oAuth2 é usado na próxima etapa.

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

Adicione as permissões para o aplicativo cliente e os componentes do aplicativo servidor para usar o fluxo de comunicação oAuth2 usando o comando az ad app permission add . Em seguida, conceda permissões para que o aplicativo cliente se comunique com o aplicativo servidor 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 as duas aplicações Microsoft Entra criadas, crie agora o próprio cluster AKS. Primeiro, crie um grupo de recursos usando o comando az group create . O exemplo a seguir 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 do locatário de sua assinatura do Azure usando o comando az account show . Em seguida, crie o cluster AKS usando o comando az aks create . O comando para criar o cluster AKS fornece os IDs do aplicativo cliente e do servidor, o segredo principal do serviço do aplicativo do servidor e o ID do 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

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

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

Criar vinculação RBAC do Kubernetes

Antes que uma conta do Microsoft Entra possa ser usada com o cluster AKS, uma associação de função ou associação de função de cluster precisa ser criada. As funções definem as permissões a serem concedidas e as associaçõ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, consulte Usando a autorização RBAC do Kubernetes.

Obtenha o nome principal do usuário (UPN) para o usuário conectado no momento usando o comando az ad signed-in-user show . Essa conta de usuário está habilitada para integração com o 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ê concede a vinculação RBAC do Kubernetes estiver no mesmo locatário do Microsoft Entra, atribua permissões com base no userPrincipalName. Se o usuário estiver em um locatário diferente do Microsoft Entra, consulte e use a propriedade objectId .

Crie um manifesto YAML nomeado basic-azure-ad-binding.yaml e cole o conteúdo a seguir. Na última linha, substitua userPrincipalName_or_objectId pela saída UPN ou ID do objeto 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 o ClusterRoleBinding usando o comando kubectl apply e especifique o nome do arquivo do seu manifesto YAML:

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

Acessar cluster com ID do Microsoft Entra

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

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

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

kubectl get pods --all-namespaces

Você recebe um prompt de entrada para autenticar usando credenciais do Microsoft Entra usando um navegador da Web. Depois de autenticado com êxito, o kubectl comando exibe os pods no cluster AKS, conforme mostrado na saída de exemplo a seguir:

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ó será solicitado a entrar novamente quando o token tiver expirado ou o arquivo de configuração do Kubernetes for recriado.

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

error: You must be logged in to the server (Unauthorized)
  • Você definiu o ID de objeto apropriado ou UPN, dependendo se a conta de usuário está no mesmo locatário do Microsoft Entra ou não.
  • O usuário não é membro de mais de 200 grupos.
  • O segredo definido no registro do aplicativo para o servidor corresponde ao valor configurado usando --aad-server-app-secret
  • Certifique-se de que apenas uma versão do kubectl está instalada na sua máquina de cada vez. 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 para a migração?

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

2. O que acontecerá se eu não tomar nenhuma medida?

Seus clusters AKS do Microsoft Entra Integration (legado) 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. Você pode enfrentar tempo de inatividade do servidor de API durante a migração.

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

Recomendamos que atualize o seu cluster AKS para o Microsoft Entra ID gerido 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 e-mail de notificação após a migração manual?

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

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

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

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

Se o cluster estiver usando o ID do Microsoft Entra gerenciado pelo AKS, a saída será managedtrue. 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óximos passos

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

Para usar usuários e grupos do Microsoft Entra para controlar o acesso aos recursos do cluster, consulte Controlar o acesso aos recursos do 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 Kubernetes, consulte Opções de acesso e identidade para AKS).

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