Autenticação do Registro de Contêiner do Azure com entidades de serviço
Você pode usar uma entidade de serviço do Microsoft Entra para fornecer push, pull ou outro acesso ao seu registro de contêiner. Usando uma entidade de serviço, você pode fornecer acesso a serviços e aplicativos "sem cabeça".
O que é um principal de serviço?
As entidades de serviço do Microsoft Entra ID fornecem acesso aos recursos do Azure na sua subscrição. Você pode pensar em uma entidade de serviço como uma identidade de usuário para um serviço, onde "serviço" é qualquer aplicativo, serviço ou plataforma que precisa acessar os recursos. Você pode configurar uma entidade de serviço com direitos de acesso definidos apenas para os recursos especificados. Em seguida, configure seu aplicativo ou serviço para usar as credenciais da entidade de serviço para acessar esses recursos.
No contexto do Registro de Contêiner do Azure, você pode criar uma entidade de serviço do Microsoft Entra com permissões pull, push and pull ou outras permissões para seu registro privado no Azure. Para obter uma lista completa, consulte Funções e permissões do Registro de Contêiner do Azure.
Por que usar uma entidade de serviço?
Usando uma entidade de serviço do Microsoft Entra, você pode fornecer acesso com escopo ao seu registro de contêiner privado. Crie entidades de serviço diferentes para cada uma das suas aplicações ou serviços, cada uma com direitos de acesso personalizados ao seu registo. E, como você pode evitar o compartilhamento de credenciais entre serviços e aplicativos, pode alternar credenciais ou revogar o acesso apenas para a entidade de serviço (e, portanto, o aplicativo) escolhido.
Por exemplo, configure seu aplicativo Web para usar uma entidade de serviço que forneça somente acesso à imagem pull , enquanto seu sistema de compilação usa uma entidade de serviço que fornece acesso push a pull ambos. Se o desenvolvimento do seu aplicativo mudar de mãos, você poderá girar suas credenciais de entidade de serviço sem afetar o sistema de compilação.
Quando usar uma entidade de serviço
Você deve usar uma entidade de serviço para fornecer acesso ao Registro em cenários sem cabeça. Ou seja, um aplicativo, serviço ou script que deve enviar ou extrair imagens de contêiner de maneira automatizada ou autônoma. Por exemplo:
Pull: implante contêineres de um registro em sistemas de orquestração, incluindo Kubernetes, DC/OS e Docker Swarm. Você também pode extrair de registros de contêiner para serviços relacionados do Azure, como Serviço de Aplicativo, Lote, Service Fabric e outros.
Gorjeta
Uma entidade de serviço é recomendada em vários cenários do Kubernetes para extrair imagens de um registro de contêiner do Azure. Com o Serviço Kubernetes do Azure (AKS), você também pode usar um mecanismo automatizado para autenticar com um registro de destino habilitando a identidade gerenciada do cluster.
- Push: crie imagens de contêiner e envie-as por push para um registro usando soluções de integração e implantação contínuas, como Azure Pipelines ou Jenkins.
Para acesso individual a um registro, como quando você puxa manualmente uma imagem de contêiner para sua estação de trabalho de desenvolvimento, recomendamos usar sua própria identidade Microsoft Entra em vez disso para acesso ao registro (por exemplo, com az acr login).
Criar um principal de serviço
Para criar uma entidade de serviço com acesso ao seu registro de contêiner, execute o seguinte script no Azure Cloud Shell ou em uma instalação local da CLI do Azure. O script é formatado para o shell Bash.
Antes de executar o script, atualize a ACR_NAME variável com o nome do seu registro de contêiner. O SERVICE_PRINCIPAL_NAME valor deve ser exclusivo dentro do locatário do Microsoft Entra. Se você receber um erro "'http://acr-service-principal' already exists.", especifique um nome diferente para a entidade de serviço.
Opcionalmente, você pode modificar o --role valor no comando az ad sp create-for-rbac se quiser conceder permissões diferentes. Para obter uma lista completa de funções, consulte Funções e permissões ACR.
Depois de executar o script, anote o ID e a senha da entidade de serviço. Depois de ter suas credenciais, você pode configurar seus aplicativos e serviços para autenticar no registro de contêiner como a entidade de serviço.
#!/bin/bash
# This script requires Azure CLI version 2.25.0 or later. Check version with `az --version`.
# Modify for your environment.
# ACR_NAME: The name of your Azure Container Registry
# SERVICE_PRINCIPAL_NAME: Must be unique within your AD tenant
ACR_NAME=$containerRegistry
SERVICE_PRINCIPAL_NAME=$servicePrincipal
# Obtain the full registry ID
ACR_REGISTRY_ID=$(az acr show --name $ACR_NAME --query "id" --output tsv)
# echo $registryId
# Create the service principal with rights scoped to the registry.
# Default permissions are for docker pull access. Modify the '--role'
# argument value as desired:
# acrpull: pull only
# acrpush: push and pull
# owner: push, pull, and assign roles
PASSWORD=$(az ad sp create-for-rbac --name $SERVICE_PRINCIPAL_NAME --scopes $ACR_REGISTRY_ID --role acrpull --query "password" --output tsv)
USER_NAME=$(az ad sp list --display-name $SERVICE_PRINCIPAL_NAME --query "[].appId" --output tsv)
# Output the service principal's credentials; use these in your services and
# applications to authenticate to the container registry.
echo "Service principal ID: $USER_NAME"
echo "Service principal password: $PASSWORD"
Usar uma entidade de serviço existente
Para conceder acesso ao Registro a uma entidade de serviço existente, você deve atribuir uma nova função à entidade de serviço. Assim como na criação de uma nova entidade de serviço, você pode conceder acesso pull, push and pull e owner, entre outros.
O script a seguir usa o comando az role assignment create para conceder permissões pull a uma entidade de serviço especificada na SERVICE_PRINCIPAL_ID variável. Ajuste o --role valor se quiser conceder um nível diferente de acesso.
#!/bin/bash
# Modify for your environment. The ACR_NAME is the name of your Azure Container
# Registry, and the SERVICE_PRINCIPAL_ID is the service principal's 'appId' or
# one of its 'servicePrincipalNames' values.
ACR_NAME=$containerRegistry
SERVICE_PRINCIPAL_ID=$servicePrincipal
# Populate value required for subsequent command args
ACR_REGISTRY_ID=$(az acr show --name $ACR_NAME --query id --output tsv)
# Assign the desired role to the service principal. Modify the '--role' argument
# value as desired:
# acrpull: pull only
# acrpush: push and pull
# owner: push, pull, and assign roles
az role assignment create --assignee $SERVICE_PRINCIPAL_ID --scope $ACR_REGISTRY_ID --role acrpull
Scripts de amostra
Você pode encontrar os scripts de exemplo anteriores para a CLI do Azure no GitHub, bem como versões para o Azure PowerShell:
Autenticar com a entidade de serviço
Depois de ter uma entidade de serviço à qual concedeu acesso ao registro de contêiner, você pode configurar suas credenciais para acesso a serviços e aplicativos "sem cabeça" ou inseri-los usando o docker login comando. Utilize os seguintes valores:
- Nome de usuário - ID do aplicativo (cliente) da entidade de serviço
- Senha - senha da entidade de serviço (segredo do cliente)
O valor Username tem o formato xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.
Gorjeta
Você pode gerar novamente a senha (segredo do cliente) de uma entidade de serviço executando o comando az ad sp credential reset .
Usar credenciais com os serviços do Azure
Você pode usar credenciais da entidade de serviço de qualquer serviço do Azure que se autentique com um registro de contêiner do Azure. Use as credenciais da entidade de serviço no lugar das credenciais de administrador do Registro para uma variedade de cenários.
Use com login docker
Você pode executar docker login usando uma entidade de serviço. No exemplo a seguir, o ID do aplicativo principal de serviço é passado na variável $SP_APP_IDde ambiente e a senha na variável $SP_PASSWD. Para obter as práticas recomendadas para gerenciar credenciais do Docker, consulte a referência do comando de login do docker.
# Log in to Docker with service principal credentials
docker login myregistry.azurecr.io --username $SP_APP_ID --password $SP_PASSWD
Uma vez conectado, o Docker armazena em cache as credenciais.
Utilização com certificado
Se tiver adicionado um certificado à sua entidade de serviço, pode iniciar sessão na CLI do Azure com autenticação baseada em certificado e, em seguida, utilizar o comando az acr login para aceder a um registo. Usar um certificado como um segredo em vez de uma senha fornece segurança adicional quando você usa a CLI.
Um certificado autoassinado pode ser criado quando você cria uma entidade de serviço. Ou adicione um ou mais certificados a uma entidade de serviço existente. Por exemplo, se você usar um dos scripts neste artigo para criar ou atualizar uma entidade de serviço com direitos para extrair ou enviar imagens de um registro, adicione um certificado usando o comando az ad sp credential reset.
Para usar a entidade de serviço com certificado para entrar na CLI do Azure, o certificado deve estar no formato PEM e incluir a chave privada. Se o certificado não estiver no formato exigido, use uma ferramenta como openssl convertê-lo. Quando você executa az login para entrar na CLI usando a entidade de serviço, forneça também a ID do aplicativo da entidade de serviço e a ID do locatário do Ative Directory. O exemplo a seguir mostra esses valores como variáveis de ambiente:
az login --service-principal --username $SP_APP_ID --tenant $SP_TENANT_ID --password /path/to/cert/pem/file
Em seguida, execute az acr login para autenticar com o registro:
az acr login --name myregistry
A CLI usa o token criado quando você executou az login para autenticar sua sessão com o registro.
Criar entidade de serviço para cenários entre locatários
Uma entidade de serviço também pode ser usada em cenários do Azure que exigem a extração de imagens de um registro de contêiner em uma ID do Microsoft Entra (locatário) para um serviço ou aplicativo em outro. Por exemplo, uma organização pode executar um aplicativo no Locatário A que precisa extrair uma imagem de um registro de contêiner compartilhado no Locatário B.
Para criar uma entidade de serviço que possa ser autenticada com um registro de contêiner em um cenário de locatário cruzado:
- Criar um aplicativo multilocatário (entidade de serviço) no Locatário A
- Provisionar o aplicativo no Locatário B
- Conceda à entidade de serviço permissões para extrair do registro no Locatário B
- Atualize o serviço ou aplicativo no Locatário A para autenticar usando a nova entidade de serviço
Para obter etapas de exemplo, consulte Extrair imagens de um registro de contêiner para um cluster AKS em um locatário do AD diferente.
Renovação da entidade de serviço
A entidade de serviço é criada com validade de um ano. Você tem opções para estender a validade por mais de um ano, ou pode fornecer a data de validade de sua escolha usando o az ad sp credential reset comando.
Próximos passos
Consulte a visão geral da autenticação para outros cenários para autenticar com um registro de contêiner do Azure.
Para obter um exemplo de como usar um cofre de chaves do Azure para armazenar e recuperar credenciais da entidade de serviço para um registro de contêiner, consulte o tutorial para criar e implantar uma imagem de contêiner usando Tarefas ACR.