Partilhar via

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. Ao usar uma entidade de serviço, é possível fornecer acesso a serviços e aplicações sem interface de utilizador.

O que é um principal de serviço?

Os representantes 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 limitados apenas aos recursos que especificar. 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 Visão geral das permissões e funções do Azure Container Registry Entra.

Por que usar um principal 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 pode evitar o compartilhamento de credenciais entre serviços e aplicações, pode mudar credenciais ou revogar o acesso apenas para o principal de serviço (e, consequentemente, a aplicação) que escolher.

Por exemplo, configure a sua aplicação web para usar uma entidade de serviço que forneça acesso apenas à imagem pull, enquanto o seu sistema de compilação utiliza uma entidade de serviço que fornece acesso tanto a push como a pull. 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 um principal de serviço para fornecer acesso ao registo em cenários sem interface gráfica. 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: Desplegar contentores de um registo 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.

    Sugestão

    É recomendado utilizar um princípio de serviço em vários cenários de Kubernetes para retirar imagens de um registo de contentores 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 "service principal"

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 tenant do Microsoft Entra. Se 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 Visão geral das permissões e funções do Azure Container Registry Entra.

Depois de executar o script, anote o ID e as credenciais do principal de serviço. Depois de ter as suas credenciais, é possível configurar os seus aplicativos e serviços para se autenticarem no registo de contentores como o principal 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ê deve executar atribuições de função para conceder permissões à entidade de serviço. Consulte Visão geral das permissões e funções do Azure Container Registry Entra.

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

Exemplos de scripts

Você pode encontrar os scripts de exemplo anteriores para a CLI do Azure no GitHub, bem como versões para o Azure PowerShell:

Autenticação 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 utilizador - ID da aplicação (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.

Sugestão

Você pode regenerar a senha (segredo do cliente) de um principal 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.

Utilize com docker login

Você pode executar docker login usando um principal 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 um principal 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 o principal de serviço com um certificado para autenticar 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 para 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 inter-locatários

Uma entidade de serviço também pode ser usada em cenários do Azure que exigem a transferência de imagens de um registro de contêiner na ID do Microsoft Entra (tenant) 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 um principal de serviço que possa autenticar-se com um registro de contêiner em um cenário de locatários cruzados:

  • Criar uma aplicação multitenant (service principal) no Tenant A
  • Provisionar o aplicativo no Locatário B
  • Conceda à entidade de serviço permissões para extrair do registo no Tenant B
  • Atualize o serviço ou aplicativo no Locatário A para autenticar usando o novo principal de serviço

Para obter etapas de exemplo, consulte Extrair imagens de um registo de contentores para um cluster AKS num locatário do Azure AD diferente.

Renovação do principal 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