创建一个具有存储库范围权限的令牌Create a token with repository-scoped permissions

本文介绍了如何创建令牌和范围映射,以便在容器注册表中管理存储库范围的权限。This article describes how to create tokens and scope maps to manage repository-scoped permissions in your container registry. 通过创建令牌,注册表所有者可以为用户或服务提供范围限定于存储库且有时间限制的访问权限,用来拉取或推送映像或执行其他操作。By creating tokens, a registry owner can provide users or services with scoped, time-limited access to repositories to pull or push images or perform other actions. 令牌提供的权限比其他注册表身份验证选项更精细,后者指定的权限范围是整个注册表。A token provides more fine-grained permissions than other registry authentication options, which scope permissions to an entire registry.

适合创建令牌的场景包括:Scenarios for creating a token include:

  • 允许具有单独令牌的 IoT 设备从存储库中拉取映像Allow IoT devices with individual tokens to pull an image from a repository
  • 向外部组织提供对特定存储库的权限Provide an external organization with permissions to a specific repository
  • 针对组织中的不同用户组限制对存储库的访问权限。Limit repository access to different user groups in your organization. 例如,为面向特定存储库构建映像的开发人员提供写入和读取访问权限,为从这些存储库进行部署的团队提供读取访问权限。For example, provide write and read access to developers who build images that target specific repositories, and read access to teams that deploy from those repositories.

重要

此功能目前以预览版提供,存在一些限制This feature is currently in preview, and some limitations apply. 需同意补充使用条款才可使用预览版。Previews are made available to you on the condition that you agree to the supplemental terms of use. 在正式版 (GA) 推出之前,此功能的某些方面可能会有所更改。Some aspects of this feature may change prior to general availability (GA).

预览版限制Preview limitations

  • 此功能仅在“高级”容器注册表中可用。This feature is only available in a Premium container registry. 有关注册表服务层级和限制的信息,请参阅 Azure 容器注册表 SKUFor information about registry service tiers and limits, see Azure Container Registry SKUs.
  • 当前无法将存储库范围的权限分配给 Azure Active Directory 标识,例如服务主体或托管标识。You can't currently assign repository-scoped permissions to an Azure Active Directory identity, such as a service principal or managed identity.
  • 无法在启用了匿名拉取访问的注册表中创建范围映射。You can't create a scope map in a registry enabled for anonymous pull access.

概念Concepts

若要配置存储库范围的权限,请创建具有关联的“范围映射”的“令牌”。To configure repository-scoped permissions, you create a token with an associated scope map.

  • 用户使用令牌与生成的密码通过注册表进行身份验证。A token along with a generated password lets the user authenticate with the registry. 你可以为令牌密码设置到期日期,或者随时禁用令牌。You can set an expiration date for a token password, or disable a token at any time.

    使用令牌进行身份验证后,用户或服务可以执行范围限定于一个或多个存储库的一个或多个操作。After authenticating with a token, the user or service can perform one or more actions scoped to one or more repositories.

    操作Action 说明Description 示例Example
    content/delete 从存储库中删除数据Remove data from the repository 删除存储库或清单Delete a repository or a manifest
    content/read 从存储库中读取数据Read data from the repository 拉取项目Pull an artifact
    content/write 将数据写入到存储库Write data to the repository content/read 一起使用来推送项目Use with content/read to push an artifact
    metadata/read 从存储库中读取元数据Read metadata from the repository 列出标记或清单List tags or manifests
    metadata/write 将元数据写入到存储库Write metadata to the repository 启用或禁用读取、写入或删除操作Enable or disable read, write, or delete operations
  • 范围映射会对你应用于令牌的存储库权限进行分组,并且可以重新应用于其他令牌。A scope map groups the repository permissions you apply to a token, and can reapply to other tokens. 每个令牌都与单个范围映射相关联。Every token is associated with a single scope map.

    使用范围映射可以执行以下操作:With a scope map:

    • 配置对一组存储库具有相同权限的多个令牌Configure multiple tokens with identical permissions to a set of repositories
    • 在范围映射中添加或删除存储库操作时更新令牌权限,或者在应用另一个范围映射时这样做Update token permissions when you add or remove repository actions in the scope map, or apply a different scope map

    Azure 容器注册表还提供了多个系统定义的范围映射,你可以应用这些映射,它们在所有存储库中具有固定的权限。Azure Container Registry also provides several system-defined scope maps you can apply, with fixed permissions across all repositories.

下图显示了令牌与范围映射之间的关系。The following image shows the relationship between tokens and scope maps.

注册表令牌与范围映射

先决条件Prerequisites

  • Azure CLI - Azure CLI 2.0.76 或更高版本中提供了用于创建和管理令牌的 Azure CLI 命令。Azure CLI - Azure CLI commands to create and manage tokens are available in Azure CLI version 2.0.76 or later. 运行 az --version 即可查找版本。Run az --version to find the version. 如果需要进行安装或升级,请参阅安装 Azure CLIIf you need to install or upgrade, see Install Azure CLI.
  • Docker - 若要通过注册表进行身份验证以拉取或推送映像,你需要一个本地 Docker 安装。Docker - To authenticate with the registry to pull or push images, you need a local Docker installation. Docker 提供适用于 macOSWindowsLinux 系统的安装说明。Docker provides installation instructions for macOS, Windows, and Linux systems.
  • 容器注册表 - 如果没有,请在你的 Azure 订阅中创建一个高级容器注册表,或升级现有注册表。Container registry - If you don't have one, create a Premium container registry in your Azure subscription, or upgrade an existing registry. 例如,使用 Azure 门户Azure CLIFor example, use the Azure portal or the Azure CLI.

创建令牌 - CLICreate token - CLI

创建令牌并指定存储库Create token and specify repositories

可使用 az acr token create 命令创建令牌。Create a token using the az acr token create command. 创建令牌时,可以指定一个或多个存储库,并在每个存储库上指定关联的操作。When creating a token, you can specify one or more repositories and associated actions on each repository. 存储库不需要已在注册表中。The repositories don't need to be in the registry yet. 若要通过指定现有范围映射来创建令牌,请参阅下一部分。To create a token by specifying an existing scope map, see the next section.

下面的示例在注册表 myregistry 中创建一个令牌,该令牌对 samples/hello-world 存储库具有以下权限:content/writecontent/readThe following example creates a token in the registry myregistry with the following permissions on the samples/hello-world repo: content/write and content/read. 默认情况下,该命令会将默认令牌状态设置为 enabled,但你随时可以将状态更新为 disabledBy default, the command sets the default token status to enabled, but you can update the status to disabled at any time.

az acr token create --name MyToken --registry myregistry \
  --repository samples/hello-world \
  content/write content/read

输出会显示有关令牌的详细信息,包括生成的两个密码。The output shows details about the token, including two generated passwords. 建议将密码保存在安全的位置,以便以后将其用于身份验证。It's recommended to save the passwords in a safe place to use later for authentication. 无法再次检索这些密码,但可以生成新密码。The passwords can't be retrieved again, but new ones can be generated.

{
  "creationDate": "2020-01-18T00:15:34.066221+00:00",
  "credentials": {
    "certificates": [],
    "passwords": [
      {
        "creationTime": "2020-01-18T00:15:52.837651+00:00",
        "expiry": null,
        "name": "password1",
        "value": "uH54BxxxxK7KOxxxxRbr26dAs8JXxxxx"
      },
      {
        "creationTime": "2020-01-18T00:15:52.837651+00:00",
        "expiry": null,
        "name": "password2",
        "value": "kPX6Or/xxxxLXpqowxxxxkA0idwLtmxxxx"
      }
    ],
    "username": "MyToken"
  },
  "id": "/subscriptions/xxxxxxxx-adbd-4cb4-c864-xxxxxxxxxxxx/resourceGroups/myresourcegroup/providers/Microsoft.ContainerRegistry/registries/myregistry/tokens/MyToken",
  "name": "MyToken",
  "objectId": null,
  "provisioningState": "Succeeded",
  "resourceGroup": "myresourcegroup",
  "scopeMapId": "/subscriptions/xxxxxxxx-adbd-4cb4-c864-xxxxxxxxxxxx/resourceGroups/myresourcegroup/providers/Microsoft.ContainerRegistry/registries/myregistry/scopeMaps/MyToken-scope-map",
  "status": "enabled",
  "type": "Microsoft.ContainerRegistry/registries/tokens"

输出包含该命令创建的范围映射的详细信息。The output includes details about the scope map the command created. 可以使用范围映射(在此处名为 MyToken-scope-map)将相同的存储库操作应用于其他令牌。You can use the scope map, here named MyToken-scope-map, to apply the same repository actions to other tokens. 或者,稍后更新范围映射以更改关联的令牌的权限。Or, update the scope map later to change the permissions of the associated tokens.

创建令牌并指定范围映射Create token and specify scope map

创建令牌的另一种方法是指定现有的范围映射。An alternative way to create a token is to specify an existing scope map. 如果还没有范围映射,请先通过指定存储库和关联的操作来创建一个。If you don't already have a scope map, first create one by specifying repositories and associated actions. 然后,在创建令牌时指定该范围映射。Then, specify the scope map when creating a token.

若要创建范围映射,请使用 az acr scope-map create 命令。To create a scope map, use the az acr scope-map create command. 以下命令创建的范围映射对前面使用的 samples/hello-world 存储库具有相同权限。The following command creates a scope map with the same permissions on the samples/hello-world repository used previously.

az acr scope-map create --name MyScopeMap --registry myregistry \
  --repository samples/hello-world \
  content/write content/read \
  --description "Sample scope map"

运行 az acr token create 来创建令牌,同时指定 MyScopeMap 范围映射。Run az acr token create to create a token, specifying the MyScopeMap scope map. 与前面的示例一样,该命令会将默认令牌状态设置为 enabledAs in the previous example, the command sets the default token status to enabled.

az acr token create --name MyToken \
  --registry myregistry \
  --scope-map MyScopeMap

输出会显示有关令牌的详细信息,包括生成的两个密码。The output shows details about the token, including two generated passwords. 建议将密码保存在安全的位置,以便以后将其用于身份验证。It's recommended to save the passwords in a safe place to use later for authentication. 无法再次检索这些密码,但可以生成新密码。The passwords can't be retrieved again, but new ones can be generated.

使用令牌进行身份验证Authenticate with token

用户或服务在使用令牌通过目标注册表进行身份验证时,会提供令牌名称作为用户名并提供其生成的密码之一。When a user or service uses a token to authenticate with the target registry, it provides the token name as a user name and one of its generated passwords. 身份验证方法取决于所配置的与令牌关联的一个或多个操作。The authentication method depends on the configured action or actions associated with the token.

操作Action 如何进行身份验证How to authenticate
content/delete Azure CLI 中的 az acr repository deleteaz acr repository delete in Azure CLI
content/read docker login

Azure CLI 中的 az acr loginaz acr login in Azure CLI
content/write docker login

Azure CLI 中的 az acr loginaz acr login in Azure CLI
metadata/read az acr repository show

az acr repository show-tags

Azure CLI 中的 az acr repository show-manifestsaz acr repository show-manifests in Azure CLI
metadata/write az acr repository untag

Azure CLI 中的 az acr repository updateaz acr repository update in Azure CLI

示例:使用令牌Examples: Use token

以下示例使用本文前面创建的令牌对存储库执行常见操作:推送和拉取映像、删除映像以及列出存储库标记。The following examples use the token created earlier in this article to perform common operations on a repository: push and pull images, delete images, and list repository tags. 最初为该令牌设置了对 samples/hello-world 存储库的推送权限(content/writecontent/read 操作)。The token was set up initially with push permissions (content/write and content/read actions) on the samples/hello-world repository.

拉取和标记测试映像Pull and tag test images

以下示例从 Docker Hub 拉取 hello-worldalpine 映像,并针对你的注册表和存储库标记它们。For the following examples, pull the hello-world and alpine images from Docker Hub, and tag them for your registry and repository.

docker pull hello-world
docker pull alpine
docker tag hello-world myregistry.azurecr.cn/samples/hello-world:v1
docker tag hello-world myregistry.azurecr.cn/samples/alpine:v1

使用令牌进行身份验证Authenticate using token

运行 docker login 以通过注册表进行身份验证,提供令牌名称作为用户名,并提供其密码之一。Run docker login to authenticate with the registry, Provide the token name as the user name, and provide one of its passwords. 令牌必须具有 Enabled 状态。The token must have the Enabled status.

以下示例针对 bash shell 进行了格式设置,并使用环境变量提供值。The following example is formatted for the bash shell, and provides the values using environment variables.

TOKEN_NAME=MyToken
TOKEN_PWD=<token password>

echo $TOKEN_PWD | docker login --username $TOKEN_NAME --password-stdin myregistry.azurecr.cn

输出应显示身份验证成功:Output should show successful authentication:

Login Succeeded

将映像推送到注册表Push images to registry

成功登录后,尝试将标记的映像推送到注册表。After successful login, attempt to push the tagged images to the registry. 由于该令牌有权将映像推送到 samples/hello-world 存储库,因此以下推送会成功:Because the token has permissions to push images to the samples/hello-world repository, the following push succeeds:

docker push myregistry.azurecr.cn/samples/hello-world:v1

该令牌无权访问 samples/alpine 存储库,因此,以下推送尝试会失败,并出现类似于“requested access to the resource is denied”的错误:The token doesn't have permissions to the samples/alpine repo, so the following push attempt fails with an error similar to requested access to the resource is denied:

docker push myregistry.azurecr.cn/samples/alpine:v1

更改推送/拉取权限Change push/pull permissions

若要更新令牌的权限,请更新关联的范围映射中的权限。To update the permissions of a token, update the permissions in the associated scope map. 更新的范围映射会立即应用于所有关联的令牌。The updated scope map is applied immediately to all associated tokens.

例如,使用对 samples/alpine 存储库的 content/writecontent/read 操作更新 MyToken-scope-map,并删除对 samples/hello-world 存储库的 content/write 操作。For example, update MyToken-scope-map with content/write and content/read actions on the samples/alpine repository, and remove the content/write action on the samples/hello-world repository.

若要使用 Azure CLI,请运行 az acr scope-map update 来更新范围映射:To use the Azure CLI, run az acr scope-map update to update the scope map:

az acr scope-map update \
  --name MyScopeMap \
  --registry myregistry \
  --add samples/alpine content/write content/read \
  --remove samples/hello-world content/write 

更新范围映射后,以下推送会成功:After updating the scope map, the following push succeeds:

docker push myregistry.azurecr.cn/samples/alpine:v1

由于范围映射对 samples/hello-world 存储库仅具有 content/read 权限,因此,尝试推送到 samples/hello-world 存储库现在会失败:Because the scope map only has the content/read permission on the samples/hello-world repository, a push attempt to the samples/hello-world repo now fails:

docker push myregistry.azurecr.cn/samples/hello-world:v1

从这两个存储库中拉取映像都会成功,因为范围映射提供了对这两个存储库的 content/read 权限:Pulling images from both repos succeeds, because the scope map provides content/read permissions on both repositories:

docker pull myregistry.azurecr.cn/samples/alpine:v1
docker pull myregistry.azurecr.cn/samples/hello-world:v1

删除映像Delete images

通过添加对 alpine 存储库的 content/delete 操作来更新范围映射。Update the scope map by adding the content/delete action to the alpine repository. 此操作允许删除存储库中的映像或删除整个存储库。This action allows deletion of images in the repository, or deletion of the entire repository.

为简洁起见,我们仅显示用来更新范围映射的 az acr scope-map update 命令:For brevity, we show only the az acr scope-map update command to update the scope map:

az acr scope-map update \
  --name MyScopeMap \
  --registry myregistry \
  --add samples/alpine content/delete

可使用以下 az acr repository delete 命令删除 samples/alpine 存储库。Use the following az acr repository delete command to delete the samples/alpine repository. 若要删除映像或存储库,不能通过 docker login 对令牌进行身份验证,To delete images or repositories, the token doesn't authenticate through docker login. 而是需要将令牌的名称和密码传递给命令。Instead, pass the token's name and password to the command. 以下示例使用本文前面创建的环境变量:The following example uses the environment variables created earlier in the article:

az acr repository delete \
  --name myregistry --repository samples/alpine \
  --username $TOKEN_NAME --password $TOKEN_PWD

显示存储库标记Show repo tags

通过添加对 hello-world 存储库的 metadata/read 操作来更新范围映射。Update the scope map by adding the metadata/read action to the hello-world repository. 此操作允许读取存储库中的清单和标记数据。This action allows reading manifest and tag data in the repository.

为简洁起见,我们仅显示用来更新范围映射的 az acr scope-map update 命令:For brevity, we show only the az acr scope-map update command to update the scope map:

az acr scope-map update \
  --name MyScopeMap \
  --registry myregistry \
  --add samples/hello-world metadata/read 

若要读取 samples/hello-world 存储库中的元数据,请运行 az acr repository show-manifestsaz acr repository show-tags 命令。To read metadata in the samples/hello-world repository, run the az acr repository show-manifests or az acr repository show-tags command.

若要读取元数据,不能通过 docker login 对令牌进行身份验证,To read metadata, the token doesn't authenticate through docker login. 而是需要将令牌的名称和密码传递给任一命令。Instead, pass the token's name and password to either command. 以下示例使用本文前面创建的环境变量:The following example uses the environment variables created earlier in the article:

az acr repository show-tags \
  --name myregistry --repository samples/hello-world \
  --username $TOKEN_NAME --password $TOKEN_PWD

示例输出:Sample output:

[
  "v1"
]

管理令牌与范围映射Manage tokens and scope maps

列出范围映射List scope maps

可以使用 az acr scope-map list 命令列出在注册表中配置的所有范围映射。Use the az acr scope-map list command to list all the scope maps configured in a registry. 例如:For example:

az acr scope-map list \
  --registry myregistry --output table

输出会显示你定义的范围映射,此外还会显示多个系统定义的供你用来配置令牌的范围映射:The output shows the scope maps you defined and several system-defined scope maps you can use to configure tokens:

NAME                 TYPE           CREATION DATE         DESCRIPTION
-------------------  -------------  --------------------  ------------------------------------------------------------
_repositories_admin  SystemDefined  2020-01-20T09:44:24Z  Can perform all read, write and delete operations on the ...
_repositories_pull   SystemDefined  2020-01-20T09:44:24Z  Can pull any repository of the registry
_repositories_push   SystemDefined  2020-01-20T09:44:24Z  Can push to any repository of the registry
MyScopeMap           UserDefined    2019-11-15T21:17:34Z  Sample scope map

显示令牌详细信息Show token details

若要查看令牌的详细信息(例如其状态和密码到期日期),请运行 az acr token show 命令。To view the details of a token, such as its status and password expiration dates, run the az acr token show command. 例如:For example:

az acr scope-map show \
  --name MyScopeMap --registry myregistry

可以使用 az acr token list 命令列出在注册表中配置的所有令牌。Use the az acr token list command to list all the tokens configured in a registry. 例如:For example:

az acr token list --registry myregistry --output table

为令牌生成密码Generate passwords for token

如果没有令牌密码,或者要生成新密码,请运行 az acr token credential generate 命令。If you don't have a token password, or you want to generate new passwords, run the az acr token credential generate command.

以下示例为 MyToken 令牌的 password1 生成新值,有效期为 30 天。The following example generates a new value for password1 for the MyToken token, with an expiration period of 30 days. 它将密码存储在环境变量 TOKEN_PWD 中。It stores the password in the environment variable TOKEN_PWD. 此示例的格式是针对 Bash shell 设置的。This example is formatted for the bash shell.

TOKEN_PWD=$(az acr token credential generate \
  --name MyToken --registry myregistry --days 30 \
  --password1 --query 'passwords[0].value' --output tsv)

使用新的范围映射更新令牌Update token with new scope map

如果要使用一个不同的范围映射来更新令牌,请运行 az acr token update 并指定新的范围映射。If you want to update a token with a different scope map, run az acr token update and specify the new scope map. 例如:For example:

az acr token update --name MyToken --registry myregistry \
  --scope-map MyNewScopeMap

提示

使用新的范围映射更新令牌后,可能需要生成新的令牌密码。After updating a token with a new scope map, you might want to generate new token passwords. 请使用 az acr token credential generate 命令。Use the az acr token credential generate command.

禁用或删除令牌Disable or delete token

可能需要临时对用户或服务禁用令牌凭据。You might need to temporarily disable use of the token credentials for a user or service.

使用 Azure CLI 运行 az acr token update 命令,将 status 设置为 disabledUsing the Azure CLI, run the az acr token update command to set the status to disabled:

az acr token update --name MyToken --registry myregistry \
  --status disabled

若要删除令牌以使利用其凭据的任何人的访问权限永久失效,请运行 az acr token delete 命令。To delete a token to permanently invalidate access by anyone using its credentials, run the az acr token delete command.

az acr token delete --name MyToken --registry myregistry

后续步骤Next steps

  • 若要管理范围映射和令牌,请使用 az acr scope-mapaz acr token 命令组中的其他命令。To manage scope maps and tokens, use additional commands in the az acr scope-map and az acr token command groups.
  • 请参阅身份验证概述,以了解通过 Azure 容器注册表进行身份验证的其他选项,包括使用 Azure Active Directory 标识、服务主体或管理员帐户。See the authentication overview for other options to authenticate with an Azure container registry, including using an Azure Active Directory identity, a service principal, or an admin account.