Autenticación de Azure Container Registry con entidades de servicio

  • Artículo

Puede usar una entidad de servicio de Microsoft Entra para proporcionar el acceso de inserción, extracción u otro para su registro de contenedor. Al usar una entidad de servicio, podrá proporcionar acceso a aplicaciones y servicios de "equipos sin periféricos".

¿Qué es una entidad de servicio?

Las entidades de servicio de Microsoft Entra ID proporcionan acceso a los recursos de Azure de la suscripción. Las entidades de servicio son como identidades de usuario para un servicio, donde "servicio" equivale a cualquier aplicación, servicio o plataforma que necesita acceder a los recursos. Puede configurar una entidad de servicio con derechos de acceso limitados solo a aquellos recursos que especifique. A continuación, configure su aplicación o servicio para usar las credenciales de la entidad de servicio y acceder a dichos recursos.

En el contexto de Azure Container Registry, puede crear una entidad de servicio de Microsoft Entra con permisos de extracción, inserción y extracción u otros permisos para su registro de privado de Azure. Para obtener una lista completa, consulte Roles y permisos de Azure Container Registry.

Razones para usar una entidad de servicio

Al usar una entidad de servicio de Microsoft Entra, podrá proporcionar acceso limitado a su registro de contenedor privado. Cree distintas entidades de servicio para cada uno de sus servicios o aplicaciones, cada una con derechos personalizados de acceso a su registro. Además, puesto que es posible evitar el uso compartido de credenciales entre servicios y aplicaciones, podrá alternar las credenciales o revocar el acceso solo a la entidad principal (y, por lo tanto, a la aplicación) que elija.

Por ejemplo, configure su aplicación web para usar una entidad de servicio que solo proporcione acceso a la imagen pull, mientras el sistema de compilación utiliza una entidad de servicio que proporciona acceso a las imágenes push y pull. Si el desarrollo de su aplicación cambia de manos, puede alternar las credenciales de entidad de servicio sin que ello afecte al sistema de compilación.

Cuándo usar una entidad de servicio

Debe usar una entidad de servicio para proporcionar acceso al registro en escenarios de equipos sin periféricos. Es decir, para cualquier aplicación, servicio o script que deba insertar o extraer imágenes de contenedor de forma automática o desatendida. Por ejemplo:

  • Extracción: se implementan los contenedores desde un Registro en sistemas de orquestación como son Kubernetes, DC/OS y Docker Swarm. También puede extraer registros de contenedor para los servicios de Azure relacionados, como App Service, Batch, Service Fabric, entre otros.

    Sugerencia

    Se recomienda usar una entidad de servicio en varios escenarios de Kubernetes para extraer imágenes de un registro de contenedor de Azure. Con Azure Kubernetes Service (AKS), también puede usar un mecanismo automatizado para autenticarse con un registro de destino mediante la habilitación de la identidad administrada del clúster.

    • Inserción: se crean imágenes de contenedor y se insertan en un Registro con soluciones de integración e implementación continuas, por ejemplo, Azure Pipelines o Jenkins.

Para obtener acceso individual a un registro, como, por ejemplo, al extraer manualmente una imagen de contenedor en la estación de trabajo de desarrollo, se recomienda usar su propia identidad de Microsoft Entra para acceder al registro (por ejemplo, con az acr login).

Creación de una entidad de servicio

Para crear una entidad de servicio con acceso al registro de contenedor, ejecute el siguiente script en Azure Cloud Shell o en una instalación local de la CLI de Azure. El script tiene el formato adecuado para el shell de Bash.

Antes de ejecutar el script, actualice la variable ACR_NAME con el nombre del registro de contenedor. El valor SERVICE_PRINCIPAL_NAME debe ser único dentro del inquilino de Microsoft Entra. Si recibe un error "'http://acr-service-principal' already exists.", especifique un nombre diferente para la entidad de servicio.

Opcionalmente, puede modificar el valor --role en el comando az ad sp create-for-rbac si desea conceder permisos diferentes. Para obtener una lista completa de roles, consulte ACR roles and permissions (Roles y permisos de ACR).

Tras ejecutar el script, tome nota del identificador y la contraseña de la entidad de servicio. Cuando disponga de las credenciales, podrá configurar las aplicaciones y los servicios para autenticarse en su registro de contenedor como la entidad de servicio.

#!/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"

Uso de una entidad de servicio existente

Para conceder al registro acceso a una entidad de servicio existente, debe asignar un nuevo rol a la entidad de servicio. Al igual que con la creación de una nueva entidad de servicio, puede conceder acceso de extracción, inserción y extracción, así como de propietario, entre otros.

El script siguiente usa el comando az role assignment create para conceder permisos de extracción a la entidad de servicio especificada en la variable SERVICE_PRINCIPAL_ID. Ajuste el valor --role si quiere conceder un nivel de acceso diferente.

#!/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

Muestras de scripts

Puede encontrar los scripts del ejemplo anterior para la CLI de Azure en GitHub, así como versiones para Azure PowerShell:

Autenticación con la entidad de servicio

Cuando disponga de una entidad de servicio con acceso a su registro de contenedor, podrá configurar sus credenciales para acceder a aplicaciones y servicios sin periféricos, o especificarlos mediante el comando docker login. Use los valores siguientes:

  • Username: identificador de la aplicación (cliente) de la entidad de servicio
  • Contraseña: contraseña (secreto de cliente) de la entidad de servicio

El valor de Nombre de usuario tiene el formato xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Sugerencia

Puede volver a generar la contraseña (secreto de cliente) de una entidad de servicio mediante el comando az ad sp credential reset.

Uso de credenciales con los servicios de Azure

Puede usar las credenciales de la entidad de servicio desde cualquier servicio de Azure que pueda autenticarse en un registro de contenedor de Azure. Use las credenciales de la entidad de servicio en lugar de las credenciales de administrador del registro para una variedad de escenarios.

Uso con el inicio de sesión de Docker

Puede ejecutar docker login mediante una entidad de servicio. En el ejemplo siguiente, el identificador de aplicación de la entidad de servicio se pasa en la variable de entorno $SP_APP_ID y la contraseña en la variable $SP_PASSWD. Si quiere ver los procedimientos recomendados para administrar credenciales de Docker, consulte la referencia del comando docker login.

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

Una vez iniciada la sesión, Docker almacena las credenciales en caché.

Uso con certificado

Si ha agregado un certificado a la entidad de servicio, puede iniciar sesión en la CLI de Azure con la autenticación basada en certificados y, a continuación, puede usar el comando az acr login para acceder a un registro. El uso de un certificado como secreto en lugar de una contraseña proporciona seguridad adicional cuando se usa la CLI.

Puede crear un certificado autofirmado durante la creación de una entidad de servicio. O bien, puede agregar uno o varios certificados a una entidad de servicio existente. Por ejemplo, si usa uno de los scripts de este artículo para crear o actualizar una entidad de servicio con derechos para extraer o insertar imágenes de un registro, agregue un certificado mediante el comando az ad sp credential reset.

Para usar la entidad de servicio con el certificado para iniciar sesión en la CLI de Azure, el certificado debe tener formato PEM e incluir la clave privada. Si el certificado no tiene el formato requerido, use una herramienta como openssl para convertirlo. Al ejecutar az login para iniciar sesión en la CLI con la entidad de servicio, proporcione también el identificador de aplicación de la entidad de servicio y el identificador de inquilino de Active Directory. En el ejemplo siguiente se muestran estos valores como variables de entorno:

az login --service-principal --username $SP_APP_ID --tenant $SP_TENANT_ID  --password /path/to/cert/pem/file

A continuación, ejecute az acr login para autenticarse con el registro:

az acr login --name myregistry

La CLI usa el token creado cuando se ejecutó az login para autenticar su sesión con el registro.

Creación de una entidad de servicio para escenarios entre inquilinos

También se puede usar una entidad de servicio en escenarios de Azure que requieren la extracción de imágenes de un registro de contenedor de Microsoft Entra ID (inquilino) a un servicio o aplicación de otro. Por ejemplo, una organización podría ejecutar una aplicación en el inquilino A que necesita extraer una imagen de un registro de contenedor compartido en el inquilino B.

Para crear una entidad de servicio que pueda autenticarse con un registro de contenedor en un escenario entre inquilinos:

  • Cree una aplicación multiinquilino (entidad de servicio) en el inquilino A
  • Aprovisione la aplicación en el inquilino B
  • Conceda permisos de la entidad de servicio para extraer del registro en el inquilino B
  • Actualice el servicio o la aplicación en el inquilino A para autenticarse con la nueva entidad de servicio

Para ver pasos de ejemplo, consulte Extracción de imágenes de un registro de contenedor a un clúster de AKS en un inquilino de AD diferente.

Renovación de una entidad de servicio

La entidad de servicio se crea con una validez de un año. Tiene opciones para ampliar la validez más de un año, o puede proporcionar la fecha de expiración que prefiera mediante el comando az ad sp credential reset.

Pasos siguientes