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

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.

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

Limitações da autenticação do kubelogin no AKS

  • Os grupos criados no Microsoft Entra são incluídos apenas pelo seu valor ObjectID e não pelo nome de exibição. O comando sAMAccountName está disponível apenas para grupos sincronizados a partir do Windows Server Active Directory local.
  • O método de autenticação da entidade de serviço funciona apenas com integração Microsoft Entra ID gerenciada, não com a integração Microsoft Entra ID herdada.
  • A entidade de serviço pode ser membro de, no máximo, 200 grupos do Microsoft Entra. Se você tiver mais de 200 grupos, use funções de aplicativo.
  • 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.
  • O método de autenticação da CLI do Azure funciona apenas com o Microsoft Entra.

Como funciona a autenticação kubelogin no AKS

Os clusters do AKS que executam o Kubernetes versão 1.24 ou posterior usam automaticamente o formato de plug-in do kubelogin exec. Os clusters que executam versões do Kubernetes anteriores à 1.24 exigem conversão manual para esse formato.

Para a maioria das interações com kubelogin, use o convert-kubeconfig subcomando. O subcomando usa o arquivo kubeconfig que você especifica em --kubeconfig ou na variável de ambiente KUBECONFIG para converter o arquivo kubeconfig final para o formato exec, de acordo com o 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. O comportamento do cache depende do método de autenticação. A autenticação por código de dispositivo, a autenticação interativa via navegador da web e a autenticação por credenciais de senha do proprietário do recurso (ROPC) armazenam em cache os registros de autenticação no diretório de cache do kubelogin. Métodos como CLI do Azure e Azure Developer CLI usam o cache gerenciado por suas respectivas ferramentas de linha de comando em vez do cache do kubelogin.

Autenticação de código do dispositivo

Código do dispositivo é o método de autenticação padrão para o subcomando convert-kubeconfig. 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.

Observação

Antes dos plugins kubelogin e executável serem lançados, o método de autenticação do Azure no kubectl tinha suporte apenas para o fluxo de código do dispositivo. Usava uma versão anterior de uma biblioteca que produz um token cuja declaração de audience tem um prefixo spn:. Não é compatível com o Microsoft Entra, que utiliza um fluxo em nome de (OBO). Quando você executa o subcomando convert-kubeconfig, o kubelogin remove o prefixo spn: da declaração de público.

Parâmetros para autenticação de código do dispositivo

A tabela a seguir descreve os parâmetros que você pode usar com a autenticação de código do dispositivo:

Parâmetro Description
-l devicecode (opcional) Especifica o método de autenticação kubelogin. Esse parâmetro é opcional porque o código do dispositivo é o método padrão.
--legacy Usa o comportamento herdado para clusters configurados com integração herdada do Microsoft Entra ID. Se o arquivo kubeconfig for para um cluster desse tipo, o kubelogin adiciona automaticamente a opção --legacy.
--cache-dir Substitui o caminho padrão do diretório de cache de token, que é ${HOME}/.kube/cache/kubelogin.

Autenticação da CLI do Azure

O método de autenticação da CLI do Azure (comando: -l azurecli) usa o contexto de usuário autenticado 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. kubelogin não grava tokens no arquivo de cache de token porque a CLI do Azure já os gerencia.

Parâmetros para autenticação da CLI do Azure

A tabela a seguir descreve os parâmetros que você pode usar com a autenticação da CLI do Azure:

Parâmetro Description
-l azurecli Especifica o método de autenticação kubelogin.
--azure-config-dir Especifica o diretório de configuração da CLI do Azure. O diretório padrão é ${HOME}/.azure.

Entrar no Azure

Entre no Azure usando o az login comando.

az login

Autenticação interativa do navegador da Web

O método de autenticação interativo do navegador da Web (comando: -l interactive) abre automaticamente um navegador da Web para autenticar o 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.

Você pode usar um token de portador ou um token PoP (Prova de Posse) com esse método de autenticação.

Parâmetros para autenticação de token de portador

A tabela a seguir descreve os parâmetros que você pode usar com a autenticação de token de portador:

Parâmetro Description
-l interactive Especifica o método de autenticação kubelogin.
--cache-dir Substitui o caminho padrão do diretório de cache de token, que é ${HOME}/.kube/cache/kubelogin.

Parâmetros para autenticação de token PoP

A tabela a seguir descreve os parâmetros que você pode usar com a autenticação de token PoP:

Parâmetro Description
-l interactive Especifica o método de autenticação kubelogin.
--pop-enabled Habilita a autenticação de token PoP.
--pop-claims Especifica as declarações de token PoP em um formato de par chave-valor. Por exemplo, u=/ARM/ID/OF/CLUSTER.

Autenticação da entidade de serviço

O método de autenticação do principal de serviço (comando: -l spn) usa um principal de serviço para autenticar 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).

Parâmetros para autenticação da entidade de serviço

A tabela a seguir descreve os parâmetros que você pode usar com a autenticação do principal de serviço:

Parâmetro Description
-l spn Especifica o método de autenticação kubelogin.
--client-id O ID da aplicação (ID do cliente) do principal de serviço.
--client-secret O segredo do cliente da entidade de serviço.

Autenticação de identidade gerenciada

Use o método de autenticação de identidade gerenciada (comando: -l msi) para aplicativos que se conectam a recursos que dão suporte à autenticação do Microsoft Entra. Exemplos incluem acessar recursos Azure, como uma VM (máquina virtual) Azure, Conjuntos de Dimensionamento de Máquinas Virtuais ou Azure Cloud Shell.

Você pode usar a identidade gerenciada padrão atribuída ao recurso ou a uma identidade gerenciada específica atribuída pelo usuário.

Parâmetros para autenticação de identidade gerenciada

A tabela a seguir descreve os parâmetros que você pode usar com a autenticação de identidade gerenciada:

Parâmetro Description
-l msi Especifica o método de autenticação kubelogin.
--client-id O ID do aplicativo (id do cliente) da identidade gerenciada atribuída pelo usuário. Se você não especificar esse parâmetro, a identidade gerenciada padrão será usada.

Autenticação de identidade de carga de trabalho

O método de autenticação de identidade de carga de trabalho (comando: -l workloadidentity) usa credenciais de identidade federadas com o Microsoft Entra para autenticar o acesso aos clusters do AKS. O método usa a autenticação integrada do Microsoft Entra. Funciona definindo as seguintes variáveis de ambiente:

Variable Description
AZURE_CLIENT_ID O ID do aplicativo Microsoft Entra federado com a identidade da 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 da carga de trabalho, como um token JWT (conta de serviço projetado do Kubernetes).
AZURE_AUTHORITY_HOST O 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 GitHub ou Argo CD, sem armazenar credenciais da 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.

Parâmetros para autenticação de identidade de carga de trabalho

A tabela a seguir descreve os parâmetros que você pode usar com a autenticação de identidade de carga de trabalho:

Parâmetro Description
-l workloadidentity Especifica o método de autenticação kubelogin.

Autenticação da CLI do Desenvolvedor do Azure

O método de autenticação da CLI de Desenvolvedor do Azure (comando: -l azd) usa o contexto autenticado que a CLI de Desenvolvedor do Azure estabelece para obter um token de acesso. O token é emitido no mesmo locatário do Microsoft Entra do azd auth login. kubelogin não grava tokens em seu cache de tokens porque a CLI do desenvolvedor do Azure os gerencia.

Este método de autenticação só funciona com o Microsoft Entra no AKS. Para obter mais informações, consulte a visão geral da CLI do Desenvolvedor do Azure.

Autenticação do Azure Pipelines

O método de autenticação Azure Pipelines (comando: -l azurepipelines) usa uma conexão de serviço Azure Resource Manager e o token de acesso do sistema do pipeline para autenticar. Esse método funciona apenas em Azure Pipelines. O pipeline deve ter uma conexão de serviço Azure Resource Manager e permitir que os scripts acessem o token OAuth.

Quando você usa uma tarefa AzureCLI@2 com uma conexão de serviço do Azure Resource Manager, o kubelogin pode usar o ID do locatário, o ID do cliente e o ID da conexão de serviço que o Azure Pipelines fornece como variáveis de ambiente. Para obter mais informações, consulte conexões de serviço do Azure Pipelines.

Warning

kubelogin também dá suporte ao método de autenticação ROPC (credencial de senha) do proprietário do recurso. Microsoft recomenda que você não use ROPC porque ele é incompatível com a autenticação multifator e alguns cenários de identidade híbrida. Para obter mais informações, consulte as orientações sobre ROPC da plataforma de identidade da Microsoft.

Exportar o caminho do arquivo kubeconfig

Antes de executar o convert-kubeconfig subcomando, exporte o caminho do arquivo kubeconfig para a variável de KUBECONFIG ambiente. Por exemplo:

export KUBECONFIG=/path/to/kubeconfig

Converter o arquivo kubeconfig

Execute o convert-kubeconfig subcomando para converter o arquivo kubeconfig para usar o plug-in exec para o método de autenticação escolhido.

kubelogin convert-kubeconfig

kubelogin convert-kubeconfig -l azurecli

# Bearer token authentication
kubelogin convert-kubeconfig -l interactive

# Proof-of-Possession (PoP) token authentication
kubelogin convert-kubeconfig -l interactive --pop-enabled --pop-claims "u=/ARM/ID/OF/CLUSTER"

  1. Execute o convert-kubeconfig subcomando para converter o arquivo kubeconfig para usar o plugin exec.

    kubelogin convert-kubeconfig -l spn

  2. Defina as variáveis de ambiente para a ID do cliente e o segredo do cliente ou o certificado do cliente. Por exemplo:

    export AZURE_CLIENT_ID=<service-principal-client-id>
export AZURE_CLIENT_SECRET=<service-principal-client-secret>

# Default managed identity authentication
kubelogin convert-kubeconfig -l msi

# Specific managed identity authentication
kubelogin convert-kubeconfig -l msi --client-id <managed-identity-client-id>

kubelogin convert-kubeconfig -l workloadidentity

Converter o arquivo kubeconfig usando a CLI do desenvolvedor do Azure

  1. Entre usando a CLI do Desenvolvedor do Azure.

    azd auth login

  2. Converta o arquivo kubeconfig para usar o método de autenticação do Azure Developer CLI.

    kubelogin convert-kubeconfig -l azd

Converter o arquivo kubeconfig em Azure Pipelines

Em uma tarefa AzureCLI@2 que usa uma conexão de serviço do Azure Resource Manager, converta o arquivo kubeconfig para usar a autenticação do Azure Pipelines.

kubelogin convert-kubeconfig -l azurepipelines

Remover tokens armazenados em cache

Remova tokens armazenados em cache usando o kubelogin remove-cache-dir comando.

kubelogin remove-cache-dir

Obter informações do nó

Obtenha informações do nó usando o kubectl get comando.

kubectl get nodes

Como usar IDs de aplicativo 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.

Application ID do aplicativo (GUID) Utilizado em
Aplicativo de servidor AKS (--server-id) 6dae42f8-4368-4678-94ff-3960e28e3630 A audiência do token para todos os métodos de autenticação do kubelogin compatíveis durante o acesso ao AKS.
Aplicativo cliente público do AKS (--client-id) 80faf920-1908-4b52-b5ef-a8e7bedfc67a Código do dispositivo, navegador da Web interativo e autenticação ROPC.

Ao chamar kubelogin get-token diretamente para o AKS, especifique a ID do aplicativo do servidor AKS com --server-id. Para parâmetros específicos do modo, consulte a referência do kubeloginget-token.

Observação

A ID do aplicativo cliente público do AKS nesta seção é o valor --client-id para código do dispositivo, interação com navegador da Web e autenticação ROPC. Para autenticação com entidade de serviço e identidade gerenciada, --client-id identifica a entidade de serviço ou a identidade gerenciada atribuída ao usuário, em vez disso.

Por exemplo, obtenha um token usando a autenticação de código do dispositivo e as IDs do aplicativo AKS:

kubelogin get-token \
    --login devicecode \
    --server-id 6dae42f8-4368-4678-94ff-3960e28e3630 \
    --client-id 80faf920-1908-4b52-b5ef-a8e7bedfc67a \
    --tenant-id <microsoft-entra-tenant-id>

Conteúdo relacionado

  • Última atualização em