Autenticação do Registro de Contêiner do Azure com entidades de serviço

  • Artigo

Você pode usar uma entidade de serviço do Microsoft Entra para fornecer push, pull ou outro acesso ao registro de contêiner. Usando uma entidade de serviço, você pode fornecer acesso a serviços e aplicativos “sem periféricos”.

O que é uma entidade de serviço?

As entidades de serviço do Microsoft Entra ID fornecem acesso aos recursos do Azure em sua assinatura. Você pode considerar uma entidade de serviço como uma identidade do usuário de um serviço, em que o “serviço” é qualquer aplicativo, serviço ou plataforma que precisa de acesso aos recursos. Você pode configurar uma entidade de serviço com direitos de acesso com escopo apenas nos 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, é possível criar uma entidade de serviço do Microsoft Entra com pull, push e pull ou outras permissões para o seu registro particular no Azure. Para obter uma lista completa de funções, confira 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 particular. Crie entidades de serviço diferentes para cada um dos aplicativos ou serviços, cada uma com direitos de acesso adaptadas ao registro. Já que você pode evitar o compartilhamento de credenciais entre serviços e aplicativos, você pode girar as credenciais ou revogar o acesso somente à entidade de serviço (e, portanto, ao aplicativo) de sua escolha.

Por exemplo, configure o aplicativo Web para usar uma entidade de serviço que fornece somente o acesso à imagem pull, enquanto o sistema de build usa uma entidade de serviço que fornece o acesso push e pull. Se o desenvolvimento do seu aplicativo for transferido para outra pessoa, você poderá girar as credenciais da entidade de serviço sem afetar o sistema de build.

Quando usar uma entidade de serviço

Você deve usar uma entidade de serviço para fornecer o acesso de registro em cenários “sem periféricos”. Em outras palavras, qualquer aplicativo, serviço ou script que precisa enviar por push ou efetuar pull de imagens de contêiner de maneira automatizada ou autônoma. Por exemplo:

  • Pull: implanta contêineres de um registro para sistemas de orquestração, incluindo DC/SO, Docker Swarm e Kubernetes. Também é possível efetuar pull de registros de contêiner para serviços do Azure relacionados, como Serviço de Aplicativo, Lote e Service Fabric, entre outros.

    Dica

    Uma entidade de serviço é recomendada em vários cenários do Kubernetes para pull de imagens de um Registro de Contêiner do Azure. Com o AKS (Serviço de Kubernetes do Azure), 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 o Azure Pipelines ou o Jenkins.

Para acesso individual a um registro, ao efetuar pull manualmente de uma imagem de contêiner para sua estação de trabalho de desenvolvimento, recomendamos usar sua própria identidade do Microsoft Entra para acessar o registro (por exemplo, com az acr login).

Criar uma entidade de serviço

Para criar uma entidade de serviço com acesso ao registro de contêiner, execute o script a seguir no Azure Cloud Shell ou uma instalação local da CLI do Azure. O script é formatado para o shell do Bash.

Antes de executar o script, atualize a variável ACR_NAME com o nome do registro de contêiner. O valor SERVICE_PRINCIPAL_NAME deve ser exclusivo no 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.

Como opção, modifique o valor --role 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 do ACR.

Depois de executar o script, anote a ID e a senha da entidade de serviço. Quando você tiver suas credenciais, poderá configurar os aplicativos e serviços para se autenticarem 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 de registro a uma entidade de serviço existente, você precisa atribuir uma nova função à entidade de serviço. Assim como ocorre ao criar uma nova entidade de serviço, é possível conceder acesso de proprietário, pull, push e pull, dentre 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 variável SERVICE_PRINCIPAL_ID. Ajuste o valor --role se você desejar 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 exemplo

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

Autenticação com a entidade de serviço

Depois que você tiver uma entidade de serviço para a qual você concedeu acesso ao registro de contêiner, será possível configurar as suas credenciais para acessar serviços e aplicativos "sem periféricos" ou inseri-los usando o comando docker login. Use os seguintes valores:

  • Nome de usuário – ID do aplicativo (cliente) da entidade de serviço
  • Senha – senha (segredo do cliente) da entidade de serviço

O valor Nome de usuário tem o formato xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Dica

Você pode regenerar 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 as credenciais da entidade de serviço de qualquer serviço do Azure que se autentica em um registro de contêiner do Azure. Use as credenciais da entidade de serviço em vez das credenciais de administrador do registro para uma variedade de cenários.

Usar com o logon do Docker

Você pode executar docker login usando uma entidade de serviço. No exemplo a seguir, a ID do aplicativo da entidade de serviço é passada na variável de ambiente $SP_APP_ID e a senha na variável $SP_PASSWD. Para obter práticas recomendadas para gerenciar as credenciais do Docker, confira a referência do comando docker login.

# Log in to Docker with service principal credentials
docker login myregistry.azurecr.io --username $SP_APP_ID --password $SP_PASSWD

Depois de conectado, o Docker armazena as credenciais em cache.

Usar com o certificado

Se você tiver adicionado um certificado à entidade de serviço, poderá entrar na CLI do Azure com autenticação baseada em certificado e usar o comando az acr login para acessar um registro. Usar um certificado como um segredo em vez de como uma senha fornece segurança adicional quando você usa a CLI.

Um certificado autoassinado pode ser criado ao criar 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 efetuar pull ou push de 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 precisa estar no formato PEM e incluir a chave privada. Se o certificado não estiver no formato necessário, use uma ferramenta como openssl para convertê-lo. Quando você executar 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 Active Directory. O seguinte exemplo 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 se autenticar com o registro:

az acr login --name myregistry

A CLI usa o token criado quando você executou o 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 o pull de imagens de um registro de contêiner em um Microsoft Entra ID (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 efetuar pull de uma imagem de um registro de contêiner compartilhado no locatário B.

Para criar uma entidade de serviço que possa se autenticar com um registro de contêiner em um cenário entre locatários:

  • Crie um aplicativo multilocatário (entidade de serviço) no locatário A
  • Provisione o aplicativo no locatário B
  • Conceder permissões à entidade de serviço para efetuar pull do registro no locatário B
  • Atualizar o serviço ou aplicativo no locatário A para se autenticar usando a nova entidade de serviço

Para etapas de exemplo, confira Efetuar pull de imagens de um registro de contêiner para um cluster do AKS em outro locatário do AD.

Renovação da entidade de serviço

A entidade de serviço é criada com validade de um ano. Você tem opções para prorrogar a validade para mais de um ano ou pode fornecer a data de validade de sua escolha usando o comando az ad sp credential reset.

Próximas etapas