Partilhar via


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

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. Para obter mais informações, consulte a introdução do kubelogin e a introdução do kubectl.

Os clusters do Serviço Kubernetes do Azure (AKS) integrados com o Microsoft Entra ID 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 o kubelogin para todos os métodos de autenticação do Microsoft Entra suportados 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 usar funções de aplicativo.
  • Os grupos criados no Microsoft Entra ID 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 Ative Directory do Windows Server local.
  • No AKS, o método de autenticação da entidade de serviço funciona apenas com o Microsoft Entra ID gerenciado e não com a versão anterior do Azure Ative 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 --kubeconfig variável de ambiente ou na KUBECONFIG 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 seguintes sinalizadores de parâmetros 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 cliente público. Este aplicativo cliente é usado somente no código do dispositivo, navegador da Web interativo e métodos de entrada OAuth 2.0 Resource Owner Password Credentials (ROPC) (identidade do fluxo de trabalho).
  • --server-id: A ID do aplicativo Web ou do servidor de recursos. O token é emitido para este recurso.

Nota

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 suportados e como usá-los:

  • Código do dispositivo
  • CLI do Azure
  • Navegador da Web interativo
  • Service principal (Principal de serviço)
  • Identidade gerida
  • 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 parâmetro é opcional. Esse método de autenticação solicita o código do dispositivo para que o usuário entre 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 suportava apenas o fluxo de código do dispositivo. Ele usou uma versão anterior de uma biblioteca que produz um token que tem a declaração com um spn: prefixoaudience. Não é compatível com o Microsoft Entra ID gerenciado pelo AKS, que usa um fluxo em nome de (OBO). Quando você executa o convert-kubeconfig subcomando, kubelogin remove o 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 uma versão anterior do cluster do Azure Ative Directory, 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

Nota

O método de entrada de código de dispositivo não funciona quando uma política 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.

Nota

Este método de autenticação funciona apenas com o Microsoft Entra ID gerido 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 --azure-config-dir parâmetro com o convert-kubeconfig 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 quando executa 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. Este método de autenticação está em conformidade com a política de Acesso Condicional.

Quando você se 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 ao 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

Service principal (Principal 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 suportadas 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:

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

Variáveis de ambiente

O exemplo a seguir mostra como configurar um segredo do 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 do 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 de cliente

O exemplo a seguir mostra como configurar um segredo do 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 gerida

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 escala 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 que são 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 asserção assinada da identidade da carga de trabalho, como um token de conta de serviço projetada (JWT) 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 a partir 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) a partir 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 o kubelogin com o AKS

O AKS usa um par de aplicativos Microsoft Entra de primeira parte. Esses IDs de aplicativo são os mesmos em todos os ambientes.

O ID do aplicativo do 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.

O 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. O ID do aplicativo cliente é usado no código do dispositivo e nos métodos de autenticação interativos do navegador da Web.