Autenticar com um Registro de contêiner do Azure
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 AzureConnect-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 loginaz acr login na CLI do AzureConnect-AzContainerRegistry no Azure PowerShellConfiguraçõ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 loginaz acr login na CLI do AzureConnect-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 loginaz acr login na CLI do AzureConnect-AzContainerRegistry no Azure PowerShellSegredo 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.
