使用 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 recommended scenarios. 有关详细信息,请参阅链接的内容。See linked content for details.

方法Method 如何进行身份验证How to authenticate 方案Scenarios  RBACRBAC  限制Limitations 
单个 AD 标识 Individual AD identity  Azure CLI 中的 az acr login  az 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  否,始终仅限拉取和推送访问No, always pull and push access  每个注册表一个帐户,不建议用于多个用户Single account per registry, not recommended for multiple users 

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

直接使用注册表时(例如向开发工作站拉取映像和从中推送映像),可通过在 Azure CLI 中使用 az acr login 命令进行身份验证:When working with your registry directly, such as pulling images to and pushing images from a development workstation, authenticate by using the az acr login command in the Azure CLI:

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。To complete the authentication flow, Docker 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 标识可提供基于角色的访问Using az acr login with Azure identities provides role-based access. 在某些情况下,你可能希望使用 Azure AD 中你自己的个人标识登录注册表。For some scenarios, you may want to log in to a registry with your own individual identity in Azure AD. 对于跨服务方案,或者若要在不想管理个人访问的情况下满足工作组或部署工作流的需求,还可以使用 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.

服务主体Service principal

如果为注册表分配了服务主体,则应用程序或服务可以将其用于无外设身份验证。If you assign a service principal to your registry, your application or service can use it for headless authentication. 服务主体允许通过基于角色的访问来访问注册表,并且可以为注册表分配多个服务主体。Service principals allow role-based access 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 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