使用 Azure 容器注册表进行身份验证Authenticate with an Azure container registry

可通过几种方法使用 Azure 容器注册表进行身份验证,并且每种方法适用于一种或多种注册表使用方案。There are several ways to authenticate with an Azure container registry, each of which is applicable to one or more registry usage scenarios.

建议的方法包括通过个人登录来直接向注册表进行身份验证,或者应用程序和容器业务流程协调程序可以通过使用 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.

身份验证选项Authentication options

下表列出了可用的身份验证方法和典型方案。The following table lists available authentication methods and typical scenarios. 有关详细信息,请参阅链接的内容。See linked content for details.

方法Method 如何进行身份验证How to authenticate 方案Scenarios Azure 基于角色的访问控制 (Azure RBAC)Azure role-based access control (Azure RBAC) 限制Limitations
单个 AD 标识Individual AD identity Azure CLI 中的 az acr loginaz acr login in Azure CLI 开发人员、测试人员的交互式推送/拉取Interactive push/pull by developers, testers Yes AD 令牌必须每隔 3 小时续订一次AD token must be renewed every 3 hours
AD 服务主体AD service principal docker login

Azure CLI 中的 az acr loginaz acr login in Azure CLI

API 或工具中的注册表登录设置Registry login settings in APIs or tooling

Kubernetes 拉取机密Kubernetes pull secret
从 CI/CD 管道进行的无人参与推送Unattended push from CI/CD pipeline

到 Azure 或外部服务的无人参与拉取Unattended pull to Azure or external services
Yes 存储过程密码默认有效期为 1 年SP password default expiry is 1 year
与 AKS 集成Integrate with AKS 创建或更新 AKS 群集时附加注册表Attach registry when AKS cluster created or updated 到 AKS 群集的无人参与拉取Unattended pull to AKS cluster 否,仅限拉取访问No, pull access only 仅适用于 AKS 群集Only available with AKS cluster
Azure 资源的托管标识Managed identity for Azure resources docker login

Azure CLI 中的  az acr loginaz acr login in Azure CLI
从 Azure CI/CD 管道进行的无人参与推送Unattended push from Azure CI/CD pipeline

到 Azure 服务的无人参与拉取Unattended pull to Azure services

Yes 仅从支持 Azure 资源托管标识的 Azure 服务使用Use only from Azure services that support managed identities for Azure resources
管理员用户Admin user docker login 各个开发人员或测试人员的交互式推送/拉取Interactive push/pull by individual developer or tester

从注册表到 Azure 应用服务或 Azure 容器实例的映像门户部署Portal deployment of image from registry to Azure App Service or Azure Container Instances
否,始终仅限拉取和推送访问No, always pull and push access 每个注册表一个帐户,不建议用于多个用户Single account per registry, not recommended for multiple users
存储库范围的访问令牌Repository-scoped access token docker login

Azure CLI 中的 az acr loginaz acr login in Azure CLI
各个开发人员或测试人员对存储库的交互式推送/拉取Interactive push/pull to repository by individual developer or tester

各个系统或外部设备对存储库的无人参与推送/拉取Unattended push/pull to repository by individual system or external device
Yes 当前未与 AD 标识集成Not currently integrated with AD identity

使用 Azure AD 进行单次登录Individual login with Azure AD

直接使用注册表时(例如向开发工作站拉取映像和从中将映像推送到创建的注册表),可使用单独的 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. 使用 az login 登录到 Azure CLI,然后运行 az acr login 命令:Sign in to the Azure CLI with az login, and then run the az acr login command:


请先运行 az cloud set -n AzureChinaCloud 更改云环境,然后才能在 Azure 中国中使用 Azure CLI。Before you can use Azure CLI in Azure China , please run az cloud set -n AzureChinaCloud first to change the cloud environment. 若要切换回 Azure 公有云,请再次运行 az cloud set -n AzureCloudIf you want to switch back to Azure Public Cloud, run az cloud set -n AzureCloud again.

az cloud set -n AzureChinaCloud
az login
az acr login --name <acrName>

使用 az acr login 登录时,CLI 将使用执行 az login 时创建的令牌和注册表对会话进行无缝身份验证。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. 若要完成身份验证流,你的环境中必须已安装且正在运行 Docker CLI 和 Docker 守护程序。To complete the authentication flow, the Docker CLI and Docker daemon must be installed and running in your environment. az acr login 使用 Docker 客户端在 docker.config 文件中设置 Azure Active Directory 令牌。az acr login uses the Docker client to set an Azure Active Directory token in the docker.config file. 以这种方式登录后,系统会缓存凭据,并且会话中的后续 docker 命令将不再需要用户名或密码。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.


当希望将 Docker 映像以外的项目(例如 OCI 项目)推送或拉取到注册表时,还可以使用 az acr login 来对单个标识进行身份验证。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.

对于注册表访问,az acr login 使用的令牌有效期为 3 小时 ,因此,建议在运行 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. 如果令牌过期,可以通过再次使用 az acr login 命令重新进行身份验证来刷新令牌。If your token expires, you can refresh it by using the az acr login command again to reauthenticate.

配合使用 az acr login 和 Azure 标识可提供 Azure 基于角色的访问控制 (Azure RBAC)Using az acr login with Azure identities provides Azure role-based access control (Azure RBAC). 在某些情况下,你可能要在 Azure AD 中使用自己的单个标识登录注册表,或使用特定 Azure 角色和权限配置其他 Azure 用户。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. 对于跨服务方案,或者若要在不想管理个人访问的情况下满足工作组或部署工作流的需求,还可以使用 Azure 资源的托管标识进行登录。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.

使用 --expose-token 运行 az acr loginaz acr login with --expose-token

在某些情况下,当 Docker 守护程序未在环境中运行时,可能需要使用 az acr login 进行身份验证。In some cases, you might need to authenticate with az acr login when the Docker daemon isn't running in your environment. 例如,你可能需要在 Azure 本地 Shell(提供 Docker CLI,但不运行 Docker 守护程序)中的脚本中运行 az acr loginFor example, you might need to run az acr login in a script in Azure local Shell, which provides the Docker CLI but doesn't run the Docker daemon.

对于此方案,请先使用 --expose-token 参数运行 az acr loginFor this scenario, run az acr login first with the --expose-token parameter. 此选项公开访问令牌,而不是通过 Docker CLI 登录。This option exposes an access token instead of logging in through the Docker CLI.

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

输出显示访问令牌(此处为缩写):Output displays the access token, abbreviated here:

  "accessToken": "eyJhbGciOiJSUzI1NiIs[...]24V7wA",
  "loginServer": "myregistry.azurecr.cn"

然后,运行 docker login,将 00000000-0000-0000-0000-000000000000 作为用户名进行传递并使用访问令牌作为密码:Then, run docker login, passing 00000000-0000-0000-0000-000000000000 as the username and using the access token as password:

docker login myregistry.azurecr.cn --username 00000000-0000-0000-0000-000000000000 --password eyJhbGciOiJSUzI1NiIs[...]24V7wA

服务主体Service principal

如果为注册表分配了服务主体,则应用程序或服务可以将其用于无外设身份验证。If you assign a service principal to your registry, your application or service can use it for headless authentication. 服务主体允许对注册表进行 Azure 基于角色的访问控制 (Azure RBAC),并且可以为注册表分配多个服务主体。Service principals allow Azure role-based access control (Azure RBAC) to a registry, and you can assign multiple service principals to a registry. 如果拥有多个服务主体,则可为不同应用程序定义不同的访问权限。Multiple service principals allow you to define different access for different applications.

容器注册表的可用角色包括:The available roles for a container registry include:

  • AcrPull :拉取AcrPull : pull

  • AcrPush :拉取和推送AcrPush : pull and push

  • 所有者 :拉取、推送和为其他用户分配角色Owner : pull, push, and assign roles to other users

有关完整的角色列表,请参阅 Azure 容器注册表角色和权限For a complete list of roles, see Azure Container Registry roles and permissions.

有关创建服务主体以使用 Azure 容器注册表进行身份验证的 CLI 脚本,以及更多指导,请参阅使用服务主体进行 Azure 容器注册表身份验证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.

管理员帐户Admin account

每个容器注册表包含一个管理员用户帐户,此帐户默认禁用。Each container registry includes an admin user account, which is disabled by default. 可以在 Azure 门户中或通过使用 Azure CLI 或其他 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. 管理员帐户对注册表具有完全权限。The admin account has full permissions to the registry.

当前对于某些方案,需要管理员帐户才能将映像从容器注册表部署到特定 Azure 服务。The admin account is currently required for some scenarios to deploy an image from a container registry to certain Azure services. 例如,在门户中将容器映像从注册表直接部署到 Azure 容器实例用于容器的 Azure Web 应用时,需要管理员帐户。For example, the admin account is needed when you deploy a container image in the portal from a registry directly to Azure Container Instances or Azure Web Apps for Containers.


管理员帐户专门用于单个用户访问注册表,主要用于测试目的。The admin account is designed for a single user to access the registry, mainly for testing purposes. 建议不要在多个用户之间共享管理帐户凭据。We do not recommend sharing the admin account credentials among multiple users. 对于使用管理员帐户进行身份验证的所有用户,他们都将显示为对注册表具有推送和拉取访问权限的单个用户。All users authenticating with the admin account appear as a single user with push and pull access to the registry. 更改或禁用此帐户会禁用使用凭据的所有用户的注册表访问权限。Changing or disabling this account disables registry access for all users who use its credentials. 建议用户和服务主体在无外设方案中使用单个标识。Individual identity is recommended for users and service principals for headless scenarios.

管理员帐户有两个密码,这两个密码都可以再生成。The admin account is provided with two passwords, both of which can be regenerated. 使用这两个密码,可以在再生成一个密码时使用另一个密码保持与注册表的连接。Two passwords allow you to maintain connection to the registry by using one password while you regenerate the other. 如果管理员帐户已启用,可以在系统提示时将用户名和/或密码传递到 docker login 命令,以对注册表进行基本身份验证。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. 例如:For example:

docker login myregistry.azurecr.cn 

有关管理登录凭据的最佳做法,请参阅 docker login 命令参考。For best practices to manage login credentials, see the docker login command reference.

若要启用现有注册表的管理员用户,可以在 Azure CLI 中使用 az acr update 命令的 --admin-enabled 参数: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

可以在 Azure 门户中启用管理员用户,操作方法如下:导航你的注册表,在“设置”下选择“访问密钥”,然后在“管理员用户”下选择“启用” 。You can enable the admin user in the Azure portal by navigating your registry, selecting Access keys under SETTINGS , then Enable under Admin user.

在 Azure 门户中启用管理员用户的用户界面

后续步骤Next steps