Autenticación con un registro de contenedor de AzureAuthenticate with an Azure container registry

Hay varias maneras de autenticar con un Azure Container Registry que se pueden aplicar a uno o más escenarios de uso de registros.There are several ways to authenticate with an Azure container registry, each of which is applicable to one or more registry usage scenarios.

Entre los modos recomendados se incluyen la autenticación en un registro directamente mediante el inicio de sesión individual o los organizadores de contenedores y aplicaciones pueden realizar una autenticación desatendida, mediante la entidad de servicio de Azure Active Directory (Azure AD).Recommended ways include authenticating to a registry directly via individual login, or your applications and container orchestrators can perform unattended, or "headless," authentication by using an Azure Active Directory (Azure AD) service principal.

Opciones de autenticaciónAuthentication options

En la tabla siguiente se enumeran los métodos de autenticación disponibles y los escenarios típicos.The following table lists available authentication methods and typical scenarios. Consulte el contenido vinculado para obtener información.See linked content for details.

MétodoMethod Cómo autenticarseHow to authenticate EscenariosScenarios Control de acceso basado en roles de Azure (RBAC de Azure)Azure role-based access control (Azure RBAC) LimitacionesLimitations
Identidad de AD individualIndividual AD identity az acr login en la CLI de Azureaz acr login in Azure CLI Inserción/extracción interactiva por parte de los desarrolladores y evaluadoresInteractive push/pull by developers, testers Yes El token de AD se debe renovar cada 3 horas.AD token must be renewed every 3 hours
Entidad de servicio de ADAD service principal docker login

az acr login en la CLI de Azureaz acr login in Azure CLI

Configuración de inicio de sesión del registro en API o herramientasRegistry login settings in APIs or tooling

Secreto de extracción de KubernetesKubernetes pull secret
Inserción desatendida desde la canalización de CI/CDUnattended push from CI/CD pipeline

Extracción desatendida a Azure o a servicios externosUnattended pull to Azure or external services
Yes La expiración predeterminada de la contraseña de SP es de 1 año.SP password default expiry is 1 year
Integración con AKSIntegrate with AKS Asocie un registro al crear o actualizar el clúster de AKS.Attach registry when AKS cluster created or updated Extracción desatendida a un clúster de AKSUnattended pull to AKS cluster No, solo acceso de extracciónNo, pull access only Solo disponible con el clúster de AKSOnly available with AKS cluster
Identidad administrada para recursos de AzureManaged identity for Azure resources docker login

az acr login en la CLI de Azureaz acr login in Azure CLI
Inserción desatendida desde la canalización de CI/CD de AzureUnattended push from Azure CI/CD pipeline

Extracción desatendida a servicios de AzureUnattended pull to Azure services

Yes Uso solo desde servicios de Azure seleccionados que admiten identidades administradas de recursos de AzureUse only from select Azure services that support managed identities for Azure resources
Usuario administradorAdmin user docker login Inserción/extracción interactiva por parte de un desarrollador o evaluadorInteractive push/pull by individual developer or tester

Implementación del portal de la imagen desde el registro a Azure App Service o Azure Container InstancesPortal deployment of image from registry to Azure App Service or Azure Container Instances
No, siempre acceso de extracción e inserciónNo, always pull and push access Una sola cuenta por registro; no se recomienda para varios usuarios.Single account per registry, not recommended for multiple users
Token de acceso con ámbito de repositorioRepository-scoped access token docker login

az acr login en la CLI de Azureaz acr login in Azure CLI
Inserción/extracción interactiva al repositorio por parte de un desarrollador o evaluadorInteractive push/pull to repository by individual developer or tester

Inserción/extracción desatendida al repositorio mediante un sistema individual o dispositivo externoUnattended push/pull to repository by individual system or external device
Yes No se integra actualmente con la identidad de ADNot currently integrated with AD identity

Inicio de sesión individual con Azure ADIndividual login with Azure AD

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.When working with your registry directly, such as pulling images to and pushing images from a development workstation to a registry you created, authenticate by using your individual Azure identity. Inicie sesión en la CLI de Azure con az login y, luego, ejecute el comando az acr login:Sign in to the Azure CLI with az login, and then run the az acr login command:

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.When you log in with az acr login, the CLI uses the token created when you executed az login to seamlessly authenticate your session with your registry. Para completar el flujo de autenticación, la CLI y el demonio de Docker deben estar instalados y ejecutarse en el entorno.To complete the authentication flow, the Docker CLI and Docker daemon must be installed and running in your environment. az acr login usa el cliente de Docker para establecer un token de Azure Active Directory en el archivo docker.config.az acr login uses the Docker client to set an Azure Active Directory token in the docker.config file. 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.Once you've logged in this way, your credentials are cached, and subsequent docker commands in your session do not require a username or password.

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.Also use az acr login to authenticate an individual identity when you want to push or pull artifacts other than Docker images to your registry, such as OCI artifacts.

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.For registry access, the token used by az acr login is valid for 3 hours, so we recommend that you always log in to the registry before running a docker command. Si el token expira, puede actualizarlo con el comando az acr login de nuevo para volver a autenticar.If your token expires, you can refresh it by using the az acr login command again to reauthenticate.

El uso de az acr login con identidades de Azure proporciona un control de acceso basado en roles de Azure (RBAC).Using az acr login with Azure identities provides Azure role-based access control (Azure RBAC). En algunos escenarios, puede que quiera iniciar sesión en un registro con su propia identidad individual de Azure AD o configurar otros usuarios de Azure con roles y permisos de Azure específicos.For some scenarios, you may want to log in to a registry with your own individual identity in Azure AD, or configure other Azure users with specific Azure roles and permissions. 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.For cross-service scenarios or to handle the needs of a workgroup or a development workflow where you don't want to manage individual access, you can also log in with a managed identity for Azure resources.

az acr login con --expose-tokenaz acr login with --expose-token

En algunos casos, puede que necesite autenticarse con az acr login cuando el demonio de Docker no se ejecuta en su entorno.In some cases, you might need to authenticate with az acr login when the Docker daemon isn't running in your environment. 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.For example, you might need to run az acr login in a script in Azure Cloud Shell, which provides the Docker CLI but doesn't run the Docker daemon.

En este escenario, ejecute az acr login primero con el parámetro --expose-token.For this scenario, run az acr login first with the --expose-token parameter. Esta opción expone un token de acceso en lugar de iniciar sesión a través de la CLI de Docker.This option exposes an access token instead of logging in through the Docker CLI.

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

La salida muestra el token de acceso, abreviado aquí:Output displays the access token, abbreviated here:

{
  "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 docker login.For registry authentication, we recommend that you store the token credential in a safe location and follow recommended practices to manage docker login) credentials. Por ejemplo, almacene el valor del token en una variable de entorno:For example, store the token value in an environment variable:

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:Then, run docker login, passing 00000000-0000-0000-0000-000000000000 as the username and using the access token as password:

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

Entidad de servicioService principal

Si asigna una entidad de servicio en el Registro, la aplicación o el servicio pueden usarla para la autenticación desatendida.If you assign a service principal to your registry, your application or service can use it for headless authentication. 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.Service principals allow Azure role-based access control (Azure RBAC) to a registry, and you can assign multiple service principals to a registry. Las distintas entidades de servicio le permiten definir un acceso diferente para distintas aplicaciones.Multiple service principals allow you to define different access for different applications.

Los roles disponibles para un Registro de contenedor incluyen:The available roles for a container registry include:

  • AcrPull: incorporación de cambiosAcrPull: pull

  • AcrPush: incorporación y envío de cambiosAcrPush: pull and push

  • Propietario: extracción, inserción y asignación de roles a otros usuariosOwner: pull, push, and assign roles to other users

Para obtener una lista completa de roles, consulte Roles y permisos de Azure Container Registry.For a complete list of roles, see Azure Container Registry roles and permissions.

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.For CLI scripts to create a service principal for authenticating with an Azure container registry, and more guidance, see Azure Container Registry authentication with service principals.

Cuenta de administradorAdmin account

Cada registro de contenedor incluye una cuenta de usuario administrador, que está deshabilitada de forma predeterminada.Each container registry includes an admin user account, which is disabled by default. Puede habilitar el usuario administrador y administrar sus credenciales en Azure Portal, mediante la CLI de Azure o con otras herramientas de Azure.You can enable the admin user and manage its credentials in the Azure portal, or by using the Azure CLI or other Azure tools. La cuenta de administrador tiene todos los permisos para el registro.The admin account has full permissions to the registry.

La cuenta de administrador se necesita actualmente en algunos escenarios para implementar una imagen de un registro de contenedor en determinados servicios de Azure.The admin account is currently required for some scenarios to deploy an image from a container registry to certain Azure services. 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.For example, the admin account is needed when you use the Azure portal to deploy a container image from a registry directly to Azure Container Instances or Azure Web Apps for Containers.

Importante

La cuenta de administrador está diseñada para que un solo usuario acceda al registro, principalmente con fines de prueba.The admin account is designed for a single user to access the registry, mainly for testing purposes. No se recomienda compartir las credenciales de cuenta de administrador entre varios usuarios.We do not recommend sharing the admin account credentials among multiple users. 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.All users authenticating with the admin account appear as a single user with push and pull access to the registry. Al cambiar o deshabilitar esta cuenta se deshabilita el acceso de registro para todos los usuarios que utilizan sus credenciales.Changing or disabling this account disables registry access for all users who use its credentials. Se recomienda la identidad individual para usuarios y entidades de servicio para escenarios desatendidos.Individual identity is recommended for users and service principals for headless scenarios.

A la cuenta de administrador se le proporcionan dos contraseñas, y las dos se pueden regenerar.The admin account is provided with two passwords, both of which can be regenerated. Las dos contraseñas le permiten mantener la conexión con el registro mediante una contraseña mientras se regenera la otra.Two passwords allow you to maintain connection to the registry by using one password while you regenerate the other. 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.If the admin account is enabled, you can pass the username and either password to the docker login command when prompted for basic authentication to the registry. Por ejemplo:For example:

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.For recommended practices to manage login credentials, see the docker login command reference.

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:To enable the admin user for an existing registry, you can use the --admin-enabled parameter of the az acr update command in the Azure CLI:

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.You can enable the admin user in the Azure portal by navigating your registry, selecting Access keys under SETTINGS, then Enable under Admin user.

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

Pasos siguientesNext steps