Usar kubelogin para autenticar usuários no Serviço de Kubernetes do Azure

  • Artigo

O plug-in kubelogin no Azure é um plug-in de credencial client-go que implementa a autenticação do Microsoft Entra. O plugin kubelogin oferece recursos que não estão disponíveis na ferramenta de linha de comando kubectl.

Os clusters do Serviço de Kubernetes do Azure (AKS) integrados à ID do Microsoft Entra e que executam o Kubernetes versão 1.24 ou posterior usam automaticamente o formato kubelogin.

Este artigo fornece uma visão geral e exemplos de como usar kubelogin para todos os métodos de autenticação do Microsoft Entra com suporte no AKS.

Limitações

  • Você pode incluir um máximo de 200 grupos em uma declaração Microsoft Entra JSON Web Token (JWT). Se você tiver mais de 200 grupos, considere o uso de funções de aplicativo.
  • Os grupos criados na ID do Microsoft Entra são incluídos apenas pelo valor ObjectID e não pelo nome para exibição. O sAMAccountName comando está disponível apenas para grupos sincronizados a partir do Active Directory do Windows Server local.
  • No AKS, o método de autenticação da entidade de serviço funciona apenas com a ID do Microsoft Entra gerenciada e não com a versão anterior do Azure Active Directory.
  • O método de autenticação de código de dispositivo não funciona quando uma política de Acesso Condicional do Microsoft Entra é definida em um locatário do Microsoft Entra. Nesse cenário, use a autenticação interativa do navegador da Web.

Como funciona a autenticação

Para a maioria das interações com kubelogin, você usa o convert-kubeconfig subcomando. O subcomando usa o arquivo kubeconfig especificado na variável de ambiente ou na --kubeconfigKUBECONFIG variável de ambiente para converter o arquivo kubeconfig final para o formato exec com base no método de autenticação especificado.

Os métodos de autenticação que o kubelogin implementa são fluxos de concessão de token do Microsoft Entra OAuth 2.0. Os sinalizadores de parâmetro a seguir são comuns de usar em subcomandos kubelogin. Em geral, esses sinalizadores estão prontos para uso quando você obtém o arquivo kubeconfig do AKS.

  • --tenant-id: A ID do locatário do Microsoft Entra.
  • --client-id: A ID do aplicativo do aplicativo cliente público. Esse aplicativo cliente é usado somente nos métodos de entrada de código do dispositivo, interativo do navegador da Web e ROPC (Resource Owner Password Credentials) (identidade de fluxo de trabalho) do OAuth 2.0.
  • --server-id: A ID do aplicativo Web ou do servidor de recursos. O token é emitido para este recurso.

Observação

Em cada método de autenticação, o token não é armazenado em cache no sistema de arquivos.

Métodos de autenticação

As próximas seções descrevem os métodos de autenticação com suporte e como usá-los:

  • Código do dispositivo
  • CLI do Azure
  • Navegador da Web interativo
  • Entidade de serviço
  • Identidade gerenciada
  • Identidade da carga de trabalho

Código do dispositivo

O código do dispositivo é o método de autenticação padrão para o convert-kubeconfig subcomando. O -l devicecode é opcional. Esse método de autenticação solicita o código do dispositivo para o usuário entrar em uma sessão do navegador.

Antes dos plug-ins kubelogin e exec serem introduzidos, o método de autenticação do Azure no kubectl dava suporte apenas ao fluxo de código do dispositivo. Ele usava uma versão anterior de uma biblioteca que produz um token que tem a audience declaração com um spn: prefixo. Ele não é compatível com o Microsoft Entra ID gerenciado pelo AKS, que usa um fluxo em nome de (OBO). Quando você executa o subcomando, kubelogin remove o convert-kubeconfig prefixo spn: da declaração de audiência.

Se seus requisitos incluírem o uso de funcionalidades de versões anteriores, adicione o --legacy argumento. Se você estiver usando o arquivo kubeconfig em um cluster do Active Directory do Azure de versão anterior, o kubelogin adicionará automaticamente o --legacy sinalizador.

Nesse método de entrada, o token de acesso e o token de atualização são armazenados em cache no diretório ${HOME}/.kube/cache/kubelogin . Para substituir esse caminho, inclua o --token-cache-dir parâmetro.

Se o cluster integrado do AKS Microsoft Entra usar o Kubernetes 1.24 ou anterior, você deverá converter manualmente o formato de arquivo kubeconfig executando os seguintes comandos:

export KUBECONFIG=/path/to/kubeconfig
kubelogin convert-kubeconfig

Execute este comando kubectl para obter informações do nó:

kubectl get nodes

Para limpar tokens armazenados em cache, execute o seguinte comando:

kubelogin remove-tokens

Observação

O método de entrada de código de dispositivo não funciona quando uma diretiva de Acesso Condicional é configurada em um locatário do Microsoft Entra. Nesse cenário, use o método interativo do navegador da Web.

CLI do Azure

O método de autenticação da CLI do Azure usa o contexto conectado que a CLI do Azure estabelece para obter o token de acesso. O token é emitido no mesmo locatário do Microsoft Entra que az logino . kubelogin não grava tokens no arquivo de cache de token porque eles já são gerenciados pela CLI do Azure.

Observação

Esse método de autenticação funciona apenas com o Microsoft Entra ID gerenciado pelo AKS.

O exemplo a seguir mostra como usar o método CLI do Azure para autenticar:

az login

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l azurecli

Execute este comando kubectl para obter informações do nó:

kubectl get nodes

Se o diretório de configuração da CLI do Azure estiver fora do diretório ${HOME}, use o parâmetro com o convert-kubeconfig--azure-config-dir subcomando. O comando gera o arquivo kubeconfig com a variável de ambiente configurada. Você pode obter a mesma configuração definindo a AZURE_CONFIG_DIR variável de ambiente para esse diretório ao executar um comando kubectl.

Navegador da Web interativo

O método interativo de autenticação do navegador da Web abre automaticamente um navegador da Web para entrar no usuário. Depois que o usuário é autenticado, o navegador redireciona para o servidor Web local usando as credenciais verificadas. Esse método de autenticação está em conformidade com a política de Acesso Condicional.

Quando você autentica usando esse método, o token de acesso é armazenado em cache no diretório ${HOME}/.kube/cache/kubelogin . Você pode substituir esse caminho usando o --token-cache-dir parâmetro.

Token do portador

O exemplo a seguir mostra como usar um token de portador com o fluxo interativo do navegador da Web:

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l interactive

Execute este comando kubectl para obter informações do nó:

kubectl get nodes

Token de prova de posse

O exemplo a seguir mostra como usar um token de Prova de Posse (PoP) com o fluxo interativo do navegador da Web:

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l interactive --pop-enabled --pop-claims "u=/ARM/ID/OF/CLUSTER"

Execute este comando kubectl para obter informações do nó:

kubectl get nodes

Entidade de serviço

Esse método de autenticação usa uma entidade de serviço para entrar no usuário. Você pode fornecer a credencial definindo uma variável de ambiente ou usando a credencial em um argumento de linha de comando. As credenciais com suporte que você pode usar são uma senha ou um certificado de cliente PFX (Personal Information Exchange).

Antes de usar esse método, considere as seguintes limitações:

  • Esse método funciona apenas com o Microsoft Entra ID gerenciado.
  • A entidade de serviço pode ser membro de no máximo 200 grupos do Microsoft Entra.

Variáveis de ambiente

O exemplo a seguir mostra como configurar um segredo de cliente usando variáveis de ambiente:

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l spn

export AAD_SERVICE_PRINCIPAL_CLIENT_ID=<Service Principal Name (SPN) client ID>
export AAD_SERVICE_PRINCIPAL_CLIENT_SECRET=<SPN secret>

Execute este comando kubectl para obter informações do nó:

kubectl get nodes

Em seguida, execute este comando:

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l spn

export AZURE_CLIENT_ID=<SPN client ID>
export AZURE_CLIENT_SECRET=<SPN secret>

Execute este comando kubectl para obter informações do nó:

kubectl get nodes

Argumento de linha de comando

O exemplo a seguir mostra como configurar um segredo de cliente em um argumento de linha de comando:

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l spn --client-id <SPN client ID> --client-secret <SPN client secret>

Execute este comando kubectl para obter informações do nó:

kubectl get nodes

Aviso

O método de argumento de linha de comando armazena o segredo no arquivo kubeconfig.

Certificado do cliente

O exemplo a seguir mostra como configurar um segredo de cliente usando um certificado de cliente:

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l spn

export AAD_SERVICE_PRINCIPAL_CLIENT_ID=<SPN client ID>
export AAD_SERVICE_PRINCIPAL_CLIENT_CERTIFICATE=/path/to/cert.pfx
export AAD_SERVICE_PRINCIPAL_CLIENT_CERTIFICATE_PASSWORD=<PFX password>

Execute este comando kubectl para obter informações do nó:

kubectl get nodes

Em seguida, execute este comando:

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l spn

export AZURE_CLIENT_ID=<SPN client ID>
export AZURE_CLIENT_CERTIFICATE_PATH=/path/to/cert.pfx
export AZURE_CLIENT_CERTIFICATE_PASSWORD=<PFX password>

Execute este comando kubectl para obter informações do nó:

kubectl get nodes

Token PoP e variáveis de ambiente

O exemplo a seguir mostra como configurar um token PoP que usa um segredo de cliente que ele obtém de variáveis de ambiente:

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l spn --pop-enabled --pop-claims "u=/ARM/ID/OF/CLUSTER"

export AAD_SERVICE_PRINCIPAL_CLIENT_ID=<SPN client ID>
export AAD_SERVICE_PRINCIPAL_CLIENT_SECRET=<SPN secret>

Execute este comando kubectl para obter informações do nó:

kubectl get nodes

Identidade gerenciada

Use o método de autenticação de identidade gerenciada para aplicativos que se conectam a recursos que oferecem suporte à autenticação do Microsoft Entra. Os exemplos incluem acessar recursos do Azure, como uma máquina virtual do Azure, um conjunto de dimensionamento de máquina virtual ou o Azure Cloud Shell.

Identidade gerenciada padrão

O exemplo a seguir mostra como usar a identidade gerenciada padrão:

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l msi

Execute este comando kubectl para obter informações do nó:

kubectl get nodes

Identidade específica

O exemplo a seguir mostra como usar uma identidade gerenciada com uma identidade específica:

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l msi --client-id <msi-client-id>

Execute este comando kubectl para obter informações do nó:

kubectl get nodes

Identidade da carga de trabalho

O método de autenticação de identidade de carga de trabalho usa credenciais de identidade federadas com o Microsoft Entra para autenticar o acesso a clusters AKS. O método usa a autenticação integrada do Microsoft Entra. Ele funciona definindo as seguintes variáveis de ambiente:

  • AZURE_CLIENT_ID: A ID do aplicativo Microsoft Entra que é federada com a identidade da carga de trabalho.
  • AZURE_TENANT_ID: A ID do locatário do Microsoft Entra.
  • AZURE_FEDERATED_TOKEN_FILE: O arquivo que contém uma declaração assinada da identidade da carga de trabalho, como um token JWT (conta de serviço projetada) do Kubernetes.
  • AZURE_AUTHORITY_HOST: A URL base de uma autoridade do Microsoft Entra. Por exemplo, https://login.microsoftonline.com/.

Você pode usar uma identidade de carga de trabalho para acessar clusters Kubernetes de sistemas CI/CD como GitHub ou ArgoCD sem armazenar credenciais de entidade de serviço nos sistemas externos. Para configurar a federação OpenID Connect (OIDC) do GitHub, consulte o exemplo de federação OIDC.

O exemplo a seguir mostra como usar uma identidade de carga de trabalho:

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l workloadidentity

Execute este comando kubectl para obter informações do nó:

kubectl get nodes

Como usar kubelogin com AKS

O AKS usa um par de aplicativos primários do Microsoft Entra. Essas IDs de aplicativo são as mesmas em todos os ambientes.

A ID do aplicativo de servidor AKS Microsoft Entra que o lado do servidor usa é 6dae42f8-4368-4678-94ff-3960e28e3630. O token de acesso que acessa clusters AKS deve ser emitido para este aplicativo. Na maioria dos métodos de autenticação kubelogin, você deve usar --server-id com kubelogin get-token.

A ID do aplicativo cliente AKS Microsoft Entra que o kubelogin usa para executar a autenticação de cliente público em nome do usuário é 80faf920-1908-4b52-b5ef-a8e7bedfc67a. A ID do aplicativo cliente é usada no código do dispositivo e nos métodos de autenticação interativa do navegador da Web.

Conteúdo relacionado