Compartilhar via

Autenticar com um Registro de contêiner do Azure

  • Artigo

Há várias maneiras de autenticar com um Registro de Contêiner do Azure, cada uma das quais é aplicável a um ou mais cenários de uso do registro.

As maneiras recomendadas incluem:

  • Autenticar um registro diretamente por meio do logon individual
  • Os aplicativos e orquestradores de contêineres podem realizar uma autenticação autônoma ou "headless" (sem interação com o usuário) usando uma entidade de serviço do Microsoft Entra

Se você usar um registro de contêiner com o AKS (Serviço de Kubernetes do Azure) ou outro cluster do Kubernetes, confira Cenários para autenticação com o Registro de Contêiner do Azure no Kubernetes.

Opções de autenticação

A tabela a seguir lista os métodos de autenticação disponíveis e cenários típicos. Confira o conteúdo vinculado para obter detalhes.

Método Como autenticar Cenários Controle de acesso baseado em função do Azure (RBAC do Azure) Limitações
Identidade individual do AD  az acr login na CLI do Azure

Connect-AzContainerRegistry no Azure PowerShell 		Push/pull interativo por desenvolvedores, testadores Sim O token do AD deve ser renovado a cada 3 horas
Entidade de serviço do AD  docker login

az acr login na CLI do Azure

Connect-AzContainerRegistry no Azure PowerShell

Configurações de login de registro em APIs ou ferramentas

Segredo de pull do Kubernetes   		 Envio autônomo por push do pipeline de CI/CD

Pull autônomo para o Azure ou serviços externos 		Sim A expiração padrão da senha do SP é de 1 ano
Identidade gerenciada para recursos do Azure  docker login

 az acr login na CLI do Azure

Connect-AzContainerRegistry no Azure PowerShell		 Push autônomo do pipeline do Azure CI/CD

Pull autônomo para os serviços do Azure

 Sim Use apenas a partir de serviços selecionados do Azure que oferecem suporte a identidades gerenciadas para recursos do Azure
Identidade gerenciada do cluster do AKS  Anexar registro quando o cluster AKS for criado ou atualizado Pull autônomo para o cluster do AKS na mesma assinatura ou em uma diferente Não, somente acesso de pull Disponível somente com o cluster AKS

Não pode ser usado para autenticação entre locatários
Entidade de serviço de cluster do AKS  Habilitar quando o cluster do AKS for criado ou atualizado Pull autônomo para o cluster do AKS do registro em outro locatário do AD Não, somente acesso de pull Disponível somente com o cluster AKS
Usuário administrador  docker login  Push/pull interativo por desenvolvedor ou testador individual

Implantação do portal da imagem do registro para o Serviço de Aplicativo do Azure ou Instâncias de Contêiner do Azure		 Não, sempre acesso de pull e envio por push Conta única por registro, não recomendada para vários usuários
Token de acesso com escopo de repositório  docker login

az acr login na CLI do Azure

Connect-AzContainerRegistry no Azure PowerShell

Segredo de pull do Kubernetes 		 Push/pull interativo para o repositório por desenvolvedor ou testador individual

Pull autônomo para o repositório por sistema individual ou dispositivo externo 		Sim Não integrado no momento com a identidade do AD

Login individual com o Microsoft Entra ID

Ao trabalhar diretamente com seu registro, como enviar imagens para e enviar imagens de uma estação de trabalho de desenvolvimento para um registro que você criou, autentique usando sua identidade individual do Azure. Entre na CLI do Azure com az login e execute o comando az acr login:

az login
az acr login --name <acrName>

Ao fazer logon com az acr login, a CLI usa o token criado quando você executou az login para, sem interrupções, autenticar a sessão com o registro. Para concluir o fluxo de autenticação, o Docker CLI e o Docker daemon devem estar instalados e em execução em seu ambiente. O az acr login usa o cliente do Docker para configurar um token do Microsoft Entra no arquivo docker.config. Depois de você fazer logon dessa maneira, suas credenciais são armazenadas em cache e os comandos docker subsequentes na sua sessão não requerem um nome de usuário ou senha.

Dica

Use também az acr login para autenticar uma identidade individual quando quiser enviar ou receber artefatos diferentes de imagens do Docker em seu registro, como artefatos OCI.

Para acesso ao registro, o token usado por az acr login é válido por 3 horas, portanto, recomendamos que você sempre faça login no registro antes de executar um comando docker. Se o token expirar, você poderá atualizá-lo usando o comando az acr login novamente para se reautenticar.

Use az acr login com identidades do Azure fornece controle de acesso baseado em função do Azure (Azure RBAC). Em algumas situações, você pode querer fazer login em um registro com sua própria identidade individual no Microsoft Entra ID ou configurar outros usuários com funções e permissões do Azure específicas. Para cenários entre serviços ou lidar com as necessidades de um grupo de trabalho ou um fluxo de trabalho de desenvolvimento no qual você não deseja gerenciar o acesso individual, também é possível fazer logon com uma identidade gerenciada de recursos do Azure.

az acr login with --expose-token

Em alguns casos, poderá ser necessário fazer a autenticação com az acr login quando o daemon do Docker não estiver em execução no seu ambiente. Por exemplo, pode ser necessário executar az acr login em um script no Azure Cloud Shell, que fornece a CLI do Docker, mas não executa o daemon do Docker.

Para esse cenário, execute az acr login primeiro com o parâmetro --expose-token. Essa opção expõe um token de acesso em vez de registrar em login por meio da CLI do Docker.

az acr login --name <acrName> --expose-token

A saída exibe o token de acesso, abreviado aqui:

{
  "accessToken": "eyJhbGciOiJSUzI1NiIs[...]24V7wA",
  "loginServer": "myregistry.azurecr.io"
}

Para autenticação de registro, recomendamos que você armazene a credencial de token em um local seguro e siga as práticas recomendadas para gerenciar credenciais de login do docker. Por exemplo, armazene o valor do token em uma variável de ambiente:

TOKEN=$(az acr login --name <acrName> --expose-token --output tsv --query accessToken)

Em seguida, execute docker login, passando 00000000-0000-0000-0000-000000000000 como o nome de usuário e usando o token de acesso como senha:

docker login myregistry.azurecr.io --username 00000000-0000-0000-0000-000000000000 --password-stdin <<< $TOKEN

Da mesma forma, você pode usar o token retornado por az acr login com o comando helm registry login para autenticar no registro:

echo $TOKEN | helm registry login myregistry.azurecr.io \
            --username 00000000-0000-0000-0000-000000000000 \
            --password-stdin

Entidade de serviço

Se você atribuir uma entidade de serviço ao registro, seu aplicativo ou serviço poderá usá-lo na autenticação remota. As entidades de serviço permitem o controle de acesso baseado em função do Azure (Azure RBAC) a um registro e você pode atribuir várias entidades de serviço a um registro. Várias entidades de serviço permitem que você defina acesso diferente para diferentes aplicativos.

O token de autenticação do ACR é criado no login no ACR e é atualizado nas operações subsequentes. O tempo de vida para esse token é de 3 horas.

As funções disponíveis para um registro de contêiner incluem:

  • AcrPull: efetuar pull

  • AcrPush: efetuar pull e push

  • Proprietário: pull, push e atribuir funções a outros usuários

Para obter uma lista completa de funções, confira Funções e permissões do Registro de Contêiner do Azure.

Para que os scripts da CLI criem uma entidade de serviço para autenticar com um registro de contêiner do Azure ou para mais diretrizes, confira Autenticação do Registro de Contêiner do Azure com entidades de serviço.

Conta de administrador

Cada registro de contêiner inclui uma conta de usuário administrador, que fica desabilitada por padrão. Você pode habilitar o usuário administrador e gerenciar as credenciais dele no portal do Azure ou usando a CLI do Azure, o Azure PowerShell ou outras ferramentas do Azure. A conta de administrador tem permissões completas para o registro.

A conta de administrador é atualmente necessária para alguns cenários para implantar uma imagem de um registro de contêiner para determinados serviços do Azure. Por exemplo, a conta de administrador é necessária quando você usa o portal do Azure para implantar uma imagem de contêiner de um registro diretamente para Instâncias de Contêiner do Azure ou Aplicativos Web para Contêineres do Azure.

Importante

A conta do administrador destina-se para um único usuário acessar o registro, principalmente para fins de teste. Não é recomendável compartilhar as credenciais da conta do administrador com vários usuários. Todos os usuários que se autenticam com a conta do administrador aparecem como um único usuário com acesso de push e de pull ao registro. Alterar ou desabilitar essa conta desabilita o acesso ao registro para todos os usuários que usam as credenciais dela. Para cenários remotos, recomenda-se identidade individual para usuários e entidades de serviço.

A conta do administrador é fornecida com duas senhas, que podem ser regeneradas. Novas senhas criadas para contas de administradores ficam disponíveis imediatamente. A regeneração de senhas para contas de administradores levará 60 segundos para replicar e ficar disponível. As duas senhas permitem manter conexões com o registro usando uma senha enquanto a outra é regenerada. Se a conta do administrador estiver habilitada, você poderá passar o nome de usuário e a senha para o comando docker login quando solicitado a informar a autenticação Básica no Registro. Por exemplo:

docker login myregistry.azurecr.io

Para obter práticas recomendadas para gerenciar as credenciais do login, confira a referência do comando docker login.

Para habilitar o usuário administrador para um registro existente, você pode usar o parâmetro --admin-enabled do comando az acr update na CLI do Azure:

az acr update -n <acrName> --admin-enabled true

Você pode habilitar o usuário administrador no Portal do Azure navegando em seu registro, selecionando Chaves de acesso em CONFIGURAÇÕES e, em seguida, Habilitar em Usuário administrador.

Habilitar a interface do usuário administrador no Portal do Azure

Faça logon com uma ferramenta de contêiner alternativa em vez do Docker

Em alguns cenários, você precisa usar ferramentas de contêiner alternativas, como podman, em vez da ferramenta de contêiner comum docker. Por exemplo: o Docker não está mais disponível no RHEL 8 e 9. Portanto, você precisa alternar sua ferramenta de contêiner.

A ferramenta de contêiner padrão é definida como docker para comandos az acr login. Se você não definir a ferramenta de contêiner padrão e o comando docker estiver ausente no seu ambiente, o seguinte erro será exibido:

az acr login --name <acrName>
2024-03-29 07:30:10.014426 An error occurred: DOCKER_COMMAND_ERROR
Please verify if Docker client is installed and running.

Para alterar a ferramenta de contêiner padrão usada pelo comando az acr login, você pode definir a variável de ambiente DOCKER_COMMAND. Por exemplo:

DOCKER_COMMAND=podman \
az acr login --name <acrName>

Observação

Será necessária a CLI do Azure versão 2.59.0 ou posterior instalada e configurada para usar esse recurso. Execute az --version para encontrar a versão. Se você precisa instalar ou atualizar, consulte Instalar a CLI do Azure.

Próximas etapas