Compartir a través de

Autenticación con un registro de contenedor de Azure

  • Artículo

Hay varias maneras de autenticar con un Azure Container Registry que se pueden aplicar a uno o más escenarios de uso de registros.

Entre las formas recomendadas se incluyen las siguientes:

  • La autenticación en un registro directamente mediante el inicio de sesión individual
  • Las aplicaciones y los orquestadores de contenedores pueden realizar la autenticación desatendida o "sin notificación" mediante una entidad de servicio de Microsoft Entra

Si usa un registro de contenedor con Azure Kubernetes Service (AKS) o con otro clúster de Kubernetes, consulte Escenarios para autenticarse con Azure Container Registry desde Kubernetes.

Opciones de autenticación

En la tabla siguiente se enumeran los métodos de autenticación disponibles y los escenarios típicos. Consulte el contenido vinculado para obtener información.

Método Cómo autenticarse Escenarios Control de acceso basado en roles de Azure (RBAC de Azure) Limitaciones
Identidad de AD individual  az acr login en la CLI de Azure

Connect-AzContainerRegistry en Azure PowerShell 		Inserción/extracción interactiva por parte de los desarrolladores y evaluadores Sí El token de AD se debe renovar cada 3 horas.
Entidad de servicio de AD  docker login

az acr login en la CLI de Azure

Connect-AzContainerRegistry en Azure PowerShell

Configuración de inicio de sesión del registro en API o herramientas

Secreto de extracción de Kubernetes   		 Inserción desatendida desde la canalización de CI/CD

Extracción desatendida a Azure o a servicios externos 		Sí La expiración predeterminada de la contraseña de SP es de 1 año
Identidad administrada para recursos de Azure  docker login

 az acr login en la CLI de Azure

Connect-AzContainerRegistry en Azure PowerShell		 Inserción desatendida desde la canalización de CI/CD de Azure

Extracción desatendida a servicios de Azure

 Sí Uso solo desde servicios de Azure seleccionados que admiten identidades administradas de recursos de Azure
Identidad administrada por el clúster de AKS  Asocie un registro al crear o actualizar el clúster de AKS. Extracción desatendida en el clúster de AKS en la misma suscripción o en otra distinta No, solo acceso de extracción Solo disponible con el clúster de AKS

No se puede usar para la autenticación entre inquilinos.
Entidad de servicio del clúster de AKS  Habilitación al crear o actualizar el clúster de AKS Extracción desatendida en el clúster de AKS desde el registro en otro inquilino de AD No, solo acceso de extracción Solo disponible con el clúster de AKS
Usuario administrador  docker login  Inserción/extracción interactiva por parte de un desarrollador o evaluador

Implementación del portal de la imagen desde el registro a Azure App Service o Azure Container Instances		 No, siempre acceso de extracción e inserción Una sola cuenta por registro; no se recomienda para varios usuarios.
Token de acceso con ámbito de repositorio  docker login

az acr login en la CLI de Azure

Connect-AzContainerRegistry en Azure PowerShell

Secreto de extracción de Kubernetes 		 Inserción/extracción interactiva al repositorio por parte de un desarrollador o evaluador

Incorporación de cambios desatendida del repositorio mediante un sistema individual o dispositivo externo 		Sí No se integra actualmente con la identidad de AD

Inicio de sesión individual con Microsoft Entra ID

Cuando trabaje con el registro directamente (por ejemplo, para realizar la extracción e inserción de imágenes en la estación de trabajo de desarrollo para un registro que ha creado), autentíquese con su identidad individual de Azure. Inicie sesión en la CLI de Azure con az login y, luego, ejecute el comando az acr login:

az login
az acr login --name <acrName>

Cuando inicie sesión con az acr login, la CLI utiliza el token creado cuando ejecuta az login para autenticar sin problemas la sesión con su registro. Para completar el flujo de autenticación, la CLI y el demonio de Docker deben estar instalados y ejecutarse en el entorno. az acr login usa el cliente de Docker para establecer un token de Microsoft Entra en el archivo docker.config. Una vez que haya iniciado sesión de este modo, las credenciales se almacenan en caché y los comandos docker posteriores de la sesión no requieren un nombre de usuario o una contraseña.

Sugerencia

Use también az acr login para autenticar una identidad individual cuando quiera insertar o extraer artefactos que no sean imágenes de Docker en el registro, como artefactos OCI.

Para acceder al registro, el token utilizado por az acr login es válido durante 3 horas, por lo que se recomienda que inicie siempre la sesión en el registro antes de ejecutar un comando docker. Si el token expira, puede actualizarlo con el comando az acr login de nuevo para volver a autenticar.

El uso de az acr login con identidades de Azure proporciona un control de acceso basado en roles de Azure (RBAC). En algunos escenarios, puede que quiera iniciar sesión en un registro con su propia identidad individual de Microsoft Entra ID o configurar otros usuarios de Azure con roles y permisos de Azure específicos. También puede iniciar sesión con una identidad administrada para recursos de Azure en los escenarios de varios servicios o a fin de satisfacer las necesidades de un grupo de trabajo o un flujo de trabajo de desarrollo donde no quiera administrar el acceso individual.

az acr login con --expose-token

En algunos casos, debe autenticarse con az acr login cuando el demonio de Docker no se ejecuta en su entorno. Por ejemplo, puede que necesite ejecutar az acr login en un script en Azure Cloud Shell, que proporciona la CLI de Docker, pero no ejecuta el demonio de Docker.

En este escenario, ejecute az acr login primero con el parámetro --expose-token. Esta opción expone un token de acceso en lugar de iniciar sesión a través de la CLI de Docker.

az acr login --name <acrName> --expose-token

La salida muestra el token de acceso, abreviado aquí:

{
  "accessToken": "eyJhbGciOiJSUzI1NiIs[...]24V7wA",
  "loginServer": "myregistry.azurecr.io"
}

Para la autenticación de registro, se recomienda almacenar la credencial de token en una ubicación segura y seguir las prácticas recomendadas para administrar las credenciales de inicio de sesión de Docker. Por ejemplo, almacene el valor del token en una variable de entorno:

TOKEN=$(az acr login --name <acrName> --expose-token --output tsv --query accessToken)

A continuación, ejecute docker login, pasando 00000000-0000-0000-0000-000000000000 como nombre de usuario y usando el token de acceso como contraseña:

docker login myregistry.azurecr.io --username 00000000-0000-0000-0000-000000000000 --password-stdin <<< $TOKEN

Del mismo modo, puede usar el token que ha devuelto az acr login mediante el comando helm registry login para autenticarse con el registro:

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

Entidad de servicio

Si asigna una entidad de servicio en el Registro, la aplicación o el servicio pueden usarla para la autenticación desatendida. Las entidades de servicio permiten el control de acceso basado en roles (RBAC de Azure) en un registro, y puede asignar varias entidades de seguridad de servicio a un registro. Las distintas entidades de servicio le permiten definir un acceso diferente para distintas aplicaciones.

El token de autenticación de ACR se crea al iniciar sesión en ACR y se actualiza tras las operaciones posteriores. El período de vida de ese token es de 3 horas.

Los roles disponibles para un Registro de contenedor incluyen:

  • AcrPull: incorporación de cambios

  • AcrPush: incorporación y envío de cambios

  • Propietario: extracción, inserción y asignación de roles a otros usuarios

Para obtener una lista completa de roles, consulte Roles y permisos de Azure Container Registry.

Para que los scripts de la CLI creen una entidad de servicio para la autenticación con Azure Container Registry y obtener más instrucciones, consulte Autenticación de Azure Container Registry con entidades de servicio.

Cuenta de administrador

Cada registro de contenedor incluye una cuenta de usuario administrador, que está deshabilitada de forma predeterminada. Puede habilitar el usuario administrador y administrar sus credenciales en Azure Portal, mediante la CLI de Azure, Azure PowerShell o con otras herramientas de Azure. La cuenta de administrador tiene todos los permisos para el registro.

La cuenta de administrador se necesita actualmente en algunos escenarios para implementar una imagen de un registro de contenedor en determinados servicios de Azure. Por ejemplo, la cuenta de administrador es necesaria cuando se usa Azure Portal para implementar una imagen de contenedor desde un registro directamente en Azure Container Instances o Azure Web App for Containers.

Importante

La cuenta de administrador está diseñada para que un solo usuario acceda al registro, principalmente con fines de prueba. No se recomienda compartir las credenciales de cuenta de administrador entre varios usuarios. Todos los usuarios que se autentican con la cuenta de administrador aparecen como un único usuario con acceso de inserción y extracción en el registro. Al cambiar o deshabilitar esta cuenta se deshabilita el acceso de registro para todos los usuarios que utilizan sus credenciales. Se recomienda la identidad individual para usuarios y entidades de servicio para escenarios desatendidos.

A la cuenta de administrador se le proporcionan dos contraseñas, y las dos se pueden regenerar. Las nuevas contraseñas creadas para las cuentas de administrador están disponibles inmediatamente. La regeneración de contraseñas para cuentas de administrador llevará 60 segundos en replicarse y estará disponible. Las dos contraseñas le permiten mantener la conexión con el registro mediante una contraseña mientras se regenera la otra. Si la cuenta de administrador está habilitada, puede pasar el nombre de usuario y cualquier contraseña al comando docker login cuando se le solicite para la autenticación básica en el registro. Por ejemplo:

docker login myregistry.azurecr.io

Si quiere ver los procedimientos recomendados para administrar credenciales de inicio de sesión, consulte la referencia del comando docker login.

Para habilitar el usuario administrador para un registro existente, puede usar el parámetro --admin-enabled del comando az acr update en la CLI de Azure:

az acr update -n <acrName> --admin-enabled true

Puede habilitar el usuario administrador en Azure Portal dirigiéndose al registro, seleccionando Claves de acceso en Configuración y Habilitar en Usuario administrador.

Activación de la interfaz de usuario administrador en Azure Portal

Inicio de sesión con una herramienta de contenedor alternativa en lugar de Docker

En algunos escenarios, debe usar herramientas de contenedor alternativas como podman en lugar de la herramienta de contenedor común docker. Por ejemplo: Docker ya no está disponible en RHEL 8 y 9, por lo que tiene que cambiar la herramienta de contenedor.

La herramienta de contenedor predeterminada se establece en docker para comandos az acr login. Si no establece la herramienta de contenedor predeterminada y falta el comando docker en el entorno, se mostrará el siguiente error:

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 cambiar la herramienta de contenedor predeterminada que usa el comando az acr login, puede establecer la variable de entorno DOCKER_COMMAND. Por ejemplo:

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

Nota:

Necesita la versión 2.59.0 o posterior de la CLI de Azure instalada y configurada para usar esta característica. Ejecute az --version para encontrar la versión. Si necesita instalarla o actualizarla, vea Instalación de la CLI de Azure.

Pasos siguientes