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

  • Artigo

O plugin kubelogin no Azure é um plugin 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 mais informações, confira a introdução ao kubelogin e a introdução ao kubectl.

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

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 com suporte no AKS.

Limitações

  • Você pode incluir um máximo de 200 grupos em uma declaração JWT (Token Web JSON) do Microsoft Entra. Se você tiver mais de 200 grupos, pense em usar funções de aplicativo.
  • Os grupos criados no Microsoft Entra ID são incluídos apenas pelo seu valor de ObjectID e não por seu nome de exibição. O comando sAMAccountName está disponível apenas para grupos sincronizados a partir do Windows Server Active Directory local.
  • No AKS, o método de autenticação de entidade de serviço funciona apenas com o Microsoft Entra ID gerenciado; não funciona com a versão anterior do Azure Active Directory.
  • O método de autenticação de código do dispositivo não funciona quando a política de Acesso Condicional do Microsoft Entra é configurada 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 o kubelogin, use o subcomando convert-kubeconfig. O subcomando usa o arquivo kubeconfig que está especificado no --kubeconfig ou na variável de ambiente KUBECONFIG para converter o arquivo kubeconfig final em um formato executável baseado no método de autenticação especificado.

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

  • --tenant-id: a ID de locatário do Microsoft Entra.
  • --client-id: a ID de aplicativo do aplicativo cliente público. Esse aplicativo cliente é usado somente nos métodos de login com código do dispositivo, com Credenciais de Senha do Proprietário do Recurso (ROPC) do OAuth 2.0 (identidade de fluxo de trabalho) e no método interativo do navegador da web.
  • --server-id: a ID de aplicativo do aplicativo web ou servidor de recursos. O token é emitido para esse recurso.

Observação

Em cada um desses métodos 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
  • Fluxo interativo do navegador da web
  • Entidade de serviço
  • Identidade gerenciada
  • Identidade da carga de trabalho

Código do dispositivo

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

Antes dos plugins kubelogin e executável serem introduzidos, o método de autenticação do Azure no kubectl tinha suporte apenas para o fluxo de código do dispositivo. O fluxo usava uma versão anterior de uma biblioteca que produz um token cuja declaração de audience tem um prefixo spn:. A opção 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 convert-kubeconfig, o kubelogin remove o prefixo spn: da declaração de audiência.

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

Nesse método de login, 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 parâmetro --token-cache-dir.

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

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

Execute esse 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 login com código do dispositivo não funciona quando a política de Acesso Condicional é configurada no 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 do az login. O kubelogin não grava os tokens no arquivo de cache de tokens porque já são gerenciados pela CLI do Azure.

Observação

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

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

az login

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l azurecli

Execute esse 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 --azure-config-dir com o subcomando convert-kubeconfig. O comando gera o arquivo kubeconfig com a variável de ambiente configurada. Você pode obter a mesma configuração definindo a variável de ambiente AZURE_CONFIG_DIR para esse diretório quando executar um comando kubectl.

Fluxo interativo do navegador da web

O método de autenticação interativo do navegador da web abre um navegador da web automaticamente para entrar no usuário. Após o usuário ser autenticado, o navegador o 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ê 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 parâmetro --token-cache-dir.

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 esse 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 esse 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 conectar o 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 de Troca de Informações Pessoais (PFX).

Antes de usar esse método, leve em conta as seguintes limitações:

  • Esse 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 ID.

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 esse 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 esse 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 esse 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

Os exemplos a seguir mostram como configurar um segredo do cliente usando um certificado do 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 esse 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 esse 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 do cliente obtido 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 esse 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 dão 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áquinas virtuais 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 esse 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 esse 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 aos clusters do AKS. O método usa a autenticação integrada do Microsoft Entra e funciona definindo as seguintes variáveis de ambiente:

  • AZURE_CLIENT_ID: a ID do aplicativo Microsoft Entra que é federada com a identidade de carga de trabalho.
  • AZURE_TENANT_ID: a ID de locatário do Microsoft Entra.
  • AZURE_FEDERATED_TOKEN_FILE: o arquivo que contém uma declaração assinada da identidade de 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 do Kubernetes a partir de sistemas de CI/CD, como o GitHub ou o ArgoCD, sem armazenar credenciais de entidade de serviço nos sistemas externos. Para configurar a federação do OpenID Connect (OIDC) do GitHub, confira o exemplo de federação do 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 esse 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 do Microsoft Entra da própria Microsoft. Essas IDs de aplicativo são as mesmas em todos os ambientes.

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

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

Conteúdo relacionado