Use kubelogin para autenticar utilizadores no Azure Kubernetes Service (AKS)

O plugin kubelogin no Azure é um plugin de client-go credential 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.

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

Limitações da autenticação Kubelogin no AKS

  • Os grupos criados no Microsoft Entra são incluídos apenas pelo seu valor ObjectID , e não pelo seu nome de visualização. O sAMAccountName comando está disponível apenas para grupos sincronizados a partir do Ative Directory do Windows Server local.
  • O método de autenticação do principal de serviço funciona apenas com integração gerida com Microsoft Entra ID, não com integração legada com Microsoft Entra ID.
  • A entidade de serviço pode ser membro de um máximo de 200 grupos do Microsoft Entra. Se tiver mais de 200 grupos, considere usar funções de aplicação.
  • 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, utilize antes a autenticação interativa do navegador web.
  • O método de autenticação CLI do Azure funciona apenas com o Microsoft Entra.

Como funciona a autenticação kubelogin no AKS

Clusters AKS que executam Kubernetes versão 1.24 ou posterior usam automaticamente o formato de plugin kubelogin exec. Clusters que executam versões Kubernetes anteriores à 1.24 requerem conversão manual para este formato.

Para a maioria das interações com kubelogin, usa o convert-kubeconfig subcomando. O subcomando utiliza o ficheiro kubeconfig que especificar em --kubeconfig ou na variável de ambiente KUBECONFIG para converter o ficheiro 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. O comportamento da cache depende do método de autenticação. O código do dispositivo, a autenticação interativa no browser e a credencial de palavra-passe do proprietário do recurso (ROPC) armazenam em cache os registos de autenticação no diretório de cache do kubelogin. Métodos como o CLI do Azure e o Azure Developer CLI utilizam a cache gerida pela respetiva ferramenta de linha de comandos em vez da cache kubelogin.

Autenticação de código de dispositivo

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

Nota

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 audience prefixospn:. Não é compatível com o Microsoft Entra, que utiliza um fluxo em nome de (OBO). Quando você executa o convert-kubeconfig subcomando, kubelogin remove o prefixo spn: da declaração de audiência.

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

A tabela seguinte descreve parâmetros que pode usar na autenticação do código do dispositivo:

Parâmetro Description
-l devicecode (opcional) Especifica o método de autenticação kubelogin. Este parâmetro é opcional porque o código do dispositivo é o método padrão.
--legacy Utiliza comportamento legado para clusters configurados com integração legada com Microsoft Entra ID. Se o ficheiro kubeconfig corresponder a esse tipo de cluster, o kubelogin adiciona automaticamente a opção --legacy.
--cache-dir Sobrescreve o caminho predefinido do diretório de cache do token, que é ${HOME}/.kube/cache/kubelogin.

Autenticação da CLI do Azure

O método de autenticação CLI do Azure (comando: -l azurecli) utiliza o contexto de entrada que o CLI do Azure estabelece para obter o token de acesso. O token é emitido no mesmo locatário do Microsoft Entra que az login. O kubelogin não escreve tokens no ficheiro cache do token porque o CLI do Azure já os gere.

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

A tabela seguinte descreve parâmetros que pode usar com a autenticação 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 do CLI do Azure. O diretório padrão é ${HOME}/.azure.

Iniciar sessão no Azure

Inicia sessão no Azure usando o az login comando.

az login

Autenticação interativa do navegador web

O método interativo de autenticação do navegador web (comando: -l interactive) abre automaticamente um navegador web para iniciar sessão com o utilizador. Depois de o utilizador ser 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.

Pode usar um token de portador ou um token de Prova de Posse (PoP) com este método de autenticação.

Parâmetros para autenticação de token portador

A tabela seguinte descreve parâmetros que pode usar com a autenticação do token portador:

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

Parâmetros para autenticação de token PoP

A tabela seguinte descreve parâmetros que pode usar com a autenticação de tokens PoP:

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

Autenticação do Service Principal

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

Parâmetros para a autenticação do principal de serviço

A tabela seguinte descreve parâmetros que pode usar na 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 (client-id) do principal do serviço.
--client-secret O segredo do cliente da principal entidade de serviço.

Autenticação de identidade gerida

Use o método de autenticação de identidade gerida (comando: -l msi) para aplicações que se ligam a recursos que suportam a autenticação Microsoft Entra. Exemplos incluem o acesso a recursos do Azure como uma máquina virtual (VM) do Azure, Conjuntos de Dimensionamento de Máquinas Virtuais ou Azure Cloud Shell.

Pode utilizar a identidade gerida por defeito atribuída ao recurso ou uma identidade gerida específica atribuída por um utilizador.

Parâmetros para autenticação de identidade gerida

A tabela seguinte descreve parâmetros que pode usar na autenticação de identidade gerida:

Parâmetro Description
-l msi Especifica o método de autenticação kubelogin.
--client-id O identificador da aplicação (ID do cliente) da identidade gerida atribuída pelo utilizador. Se não especificar este parâmetro, é usada a identidade gerida por defeito.

Autenticação de identidade de carga de trabalho

O método de autenticação de identidade da carga de trabalho (comando: -l workloadidentity) utiliza 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:

Variable Description
AZURE_CLIENT_ID O ID de aplicação do Microsoft Entra que está federado com a identidade de trabalho.
AZURE_TENANT_ID O ID de inquilino do Microsoft Entra.
AZURE_FEDERATED_TOKEN_FILE O ficheiro que contém uma asserção assinada da identidade da carga de trabalho, como um token de conta de serviço projetada Kubernetes (JWT).
AZURE_AUTHORITY_HOST A URL base de uma autoridade Microsoft Entra. Por exemplo, https://login.microsoftonline.com/.

Pode usar uma identidade de carga de trabalho para aceder a clusters Kubernetes a partir de sistemas CI/CD como GitHub ou Argo CD sem armazenar credenciais de principal 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.

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

A tabela seguinte descreve parâmetros que pode usar com a autenticação da identidade da carga de trabalho:

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

Autenticação da Azure Developer CLI

O método de autenticação da CLI (comando: -l azd) do Azure Developer utiliza o contexto de entrada que a CLI do Azure Developer estabelece para obter o token de acesso. O token é emitido no mesmo locatário do Microsoft Entra que azd auth login. O kubelogin não escreve tokens na cache de tokens porque a CLI do Azure Developer os gere.

Este método de autenticação funciona apenas com o Microsoft Entra gerido no AKS. Para mais informações, consulte a visão geral da CLI para Desenvolvedores do Azure.

Autenticação do Azure Pipelines

O método de autenticação Azure Pipelines (comando: -l azurepipelines) utiliza uma ligação de serviço do Azure Resource Manager e o token de acesso ao sistema do pipeline para autenticar. Este método funciona apenas no Azure Pipelines. O pipeline deve ter uma ligação de serviço do Azure Resource Manager e permitir que scripts acedam ao token OAuth.

Quando utiliza uma tarefa AzureCLI@2 com uma ligação de serviço do Azure Resource Manager, o kubelogin pode utilizar o ID do tenant, o ID do cliente e o ID da ligação de serviço que o Azure Pipelines fornece como variáveis de ambiente. Para mais informações, consulte Azure Pipelines service connections.

Warning

O kubelogin também suporta o método de autenticação da credencial de palavra-passe do proprietário do recurso (ROPC). A Microsoft recomenda que não uses ROPC porque é incompatível com autenticação multifator e alguns cenários de identidade híbrida. Para mais informações, consulte as orientações sobre ROPC da plataforma de identidades da Microsoft.

Exportar o caminho do ficheiro kubeconfig

Antes de executares o convert-kubeconfig subcomando, exporta o caminho do ficheiro kubeconfig para a KUBECONFIG variável de ambiente. Por exemplo:

export KUBECONFIG=/path/to/kubeconfig

Converter o ficheiro kubeconfig

Executa o convert-kubeconfig subcomando para converter o ficheiro kubeconfig para usar o plugin exec como 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. Executa o convert-kubeconfig subcomando para converter o ficheiro kubeconfig para usar o plugin exec.

    kubelogin convert-kubeconfig -l spn

  2. Defina as variáveis de ambiente para o identificador do cliente, 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 ficheiro kubeconfig usando o Azure Developer CLI

  1. Inicie sessão usando a CLI do Azure Developer.

    azd auth login

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

    kubelogin convert-kubeconfig -l azd

Converta o ficheiro kubeconfig no Azure Pipelines

Numa tarefa AzureCLI@2 que utiliza uma ligação de serviço do Azure Resource Manager, converta o ficheiro kubeconfig para utilizar a autenticação do Azure Pipelines.

kubelogin convert-kubeconfig -l azurepipelines

Remover tokens em cache

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

kubelogin remove-cache-dir

Obter informação sobre o nó

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

kubectl get nodes

Como usar IDs de aplicação kubelogin com 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.

Application ID da Aplicação (GUID) Usado em
Aplicação servidor AKS (--server-id) 6dae42f8-4368-4678-94ff-3960e28e3630 O destinatário do token de todos os métodos de autenticação kubelogin suportados ao aceder ao AKS.
Aplicação cliente pública AKS (--client-id) 80faf920-1908-4b52-b5ef-a8e7bedfc67a Código do dispositivo, interatividade do navegador web e autenticação ROPC.

Quando chamar kubelogin get-token diretamente para o AKS, especifique o ID da aplicação do servidor AKS com --server-id. Para parâmetros específicos de cada modo, veja a referência kubeloginget-token.

Nota

O ID da aplicação cliente pública do AKS nesta secção corresponde ao valor --client-id para autenticação por código de dispositivo, autenticação interativa no navegador e autenticação ROPC. Para a autenticação com entidade de serviço e identidade gerida, --client-id identifica a entidade de serviço ou a identidade gerida atribuída pelo utilizador.

Por exemplo, obtenha um token usando autenticação por código de dispositivo e os IDs de aplicação do 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údos relacionados

  • Última atualização a