Partilhar via


Autenticar com um registo de contentor 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 formas recomendadas incluem:

  • Autenticar em um registro diretamente através de login individual
  • Aplicativos e orquestradores de contêineres podem executar autenticação autônoma ou "sem cabeça" usando uma entidade de serviço Microsoft Entra

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

Opções de autenticação

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

Método Como autenticar Cenários Controle de acesso baseado em função do Azure (Azure RBAC) 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 do Registro em APIs ou ferramentas

Kubernetes puxam segredo   
Push autônomo 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
Envio autônomo do pipeline de CI/CD do Azure

Pull autônomo para serviços do Azure

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

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

Implantação de imagem do Registro no Serviço de Aplicativo do Azure ou nas Instâncias de Contêiner do Azure
Não, puxe e empurre sempre o acesso 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

Kubernetes puxam segredo 
Push/pull interativo para o repositório por desenvolvedor ou testador individual

Pull autônomo do repositório por sistema individual ou dispositivo externo
Sim Atualmente não integrado com a identidade do AD

Login individual com ID do Microsoft Entra

Ao trabalhar diretamente com seu registro, como extrair imagens e enviar imagens de uma estação de trabalho de desenvolvimento para um registro que você criou, autentique-se 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>

Quando você efetua login com az acr logino , a CLI usa o token criado quando você executou az login para autenticar perfeitamente sua sessão com seu registro. Para concluir o fluxo de autenticação, a CLI do Docker e o daemon do Docker devem ser instalados e executados em seu ambiente. az acr login usa o cliente Docker para definir um token Microsoft Entra no docker.config arquivo. Depois de iniciar sessão desta forma, as suas credenciais são armazenadas em cache e os comandos subsequentes docker na sua sessão não requerem um nome de utilizador ou palavra-passe.

Gorjeta

Use também az acr login para autenticar uma identidade individual quando quiser enviar ou extrair artefatos diferentes de imagens do Docker para 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 docker comando. Se o token expirar, você poderá atualizá-lo usando o az acr login comando novamente para autenticar novamente.

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

az acr login com --expose-token

Em alguns casos, você precisa autenticar quando az acr login o daemon do Docker não está em execução em seu ambiente. Por exemplo, talvez seja necessário executar az acr login 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 --expose-token parâmetro. Essa opção expõe um token de acesso em vez de efetuar 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 do Registro, recomendamos que você armazene a credencial de token em um local seguro e siga as práticas recomendadas para gerenciar as 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 helm registry login comando para autenticar com o registro:

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

Service principal (Principal de serviço)

Se você atribuir uma entidade de serviço ao seu registro, seu aplicativo ou serviço poderá usá-la para autenticação sem cabeça. 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 definir diferentes acessos para diferentes aplicativos.

O token de autenticação ACR é criado após o 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: puxar

  • AcrPush: puxe e empurre

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

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

Para scripts de CLI para criar uma entidade de serviço para autenticação com um registro de contêiner do Azure e mais orientações, consulte Autenticação do Registro de Contêiner do Azure com entidades de serviço.

Conta de administrador

Cada registo de contentor inclui uma conta de utilizador administrador, que está desativada por predefinição. Você pode habilitar o usuário administrador e gerenciar suas credenciais 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 totais para o registo.

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 nas Instâncias de Contêiner do Azure ou nos Aplicativos Web do Azure para Contêineres.

Importante

A conta de administrador foi concebida para que um único utilizador aceda ao registo, principalmente para fins de teste. Não recomendamos a partilha das credenciais da conta de administrador entre vários utilizadores. Todos os utilizadores que façam a autenticação com a conta de administrador aparecem como um único utilizador com acesso push e pull ao registo. Alterar ou desativar essa conta desabilita o acesso ao Registro para todos os usuários que usam suas credenciais. A identidade individual é recomendada para usuários e entidades de serviço para cenários sem cabeça.

A conta de administrador é fornecida com duas senhas, ambas podem ser regeneradas. Novas senhas criadas para contas de administrador estão disponíveis imediatamente. A regeneração de senhas para contas de administrador levará 60 segundos para ser replicada e estar disponível. Duas senhas permitem que você mantenha a conexão com o registro usando uma senha enquanto você regenera a outra. Se a conta de administrador estiver habilitada, você poderá passar o nome de usuário e a senha para o docker login comando quando for solicitada a autenticação básica para o Registro. Por exemplo:

docker login myregistry.azurecr.io

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

Para habilitar o usuário administrador para um registro existente, você pode usar o --admin-enabled parâmetro 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 pelo 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 login 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 dockerde contêiner comum. Por exemplo: o Docker não está mais disponível no RHEL 8 e 9, então você precisa alternar sua ferramenta de contêiner.

A ferramenta de contêiner padrão é definida como docker para az acr login comandos. Se você não definir a ferramenta de contêiner padrão e o docker comando estiver faltando em 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 az acr login comando, você pode definir a variável DOCKER_COMMANDde ambiente . Por exemplo:

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

Nota

Você precisa da CLI do Azure versão 2.59.0 ou posterior instalada e configurada para usar esse recurso. Executar az --version para localizar a versão. Se precisar de instalar ou atualizar, veja Install Azure CLI (Instalar o Azure CLI).

Próximos passos