创建具有存储库范围权限的令牌

本文介绍了如何创建令牌和范围映射,以便在容器注册表中管理对特定存储库的访问权限。 通过创建令牌,注册表所有者可以为用户或服务提供范围限定于存储库且有时间限制的访问权限,用来拉取或推送映像或执行其他操作。 令牌提供的权限比其他注册表身份验证选项更精细,后者指定的权限范围是整个注册表。

适合创建令牌的场景包括:

  • 允许具有单独令牌的 IoT 设备从存储库中拉取映像
  • 向外部组织提供对特定存储库的权限
  • 针对组织中的不同用户组限制对存储库的访问权限。 例如,为面向特定存储库构建映像的开发人员提供写入和读取访问权限,为从这些存储库进行部署的团队提供读取访问权限。

此功能在“高级”容器注册表服务层级中可用。 若要了解注册表服务层和限制,请参阅 Azure 容器注册表服务层

重要

此功能目前以预览版提供,存在一些限制。 需同意补充使用条款才可使用预览版。 在正式版 (GA) 推出之前,此功能的某些方面可能会有所更改。

预览版限制

  • 当前无法将存储库范围的权限分配给 Azure Active Directory 标识,例如服务主体或托管标识。
  • 无法在启用了匿名拉取访问的注册表中创建范围映射。

概念

若要配置存储库范围内的权限,请创建具有关联的“范围映射”的“令牌” 。

  • 用户使用令牌与生成的密码对注册表进行身份验证。 你可以为令牌密码设置到期日期,或者随时禁用令牌。

    使用令牌进行身份验证后,用户或服务可以执行范围限定于一个或多个存储库的一个或多个操作。

    操作 说明 示例
    content/delete 从存储库中删除数据 删除存储库或清单
    content/read 从存储库中读取数据 拉取项目
    content/write 将数据写入存储库 content/read 一起使用以推送项目
    metadata/read 从存储库中读取元数据 列出标记或清单
    metadata/write 将元数据写入存储库 启用或禁用读取、写入或删除操作
  • 范围映射会对你应用于令牌的存储库权限进行分组,并且可以重新应用于其他令牌。 每个令牌都与单个范围映射相关联。

    使用范围映射可以执行以下操作:

    • 配置对一组存储库具有相同权限的多个令牌
    • 在范围映射中添加或删除存储库操作时更新令牌权限,或者在应用另一个范围映射时这样做

    Azure 容器注册表还提供了几个系统定义的范围映射,你可以在创建令牌时应用这些映射。 系统定义的范围映射的权限适用于注册表中的所有存储库。

下图显示了令牌与范围映射之间的关系。

注册表令牌和范围映射

先决条件

  • Azure CLI - 本文中的 Azure CLI 命令示例需要 Azure CLI 2.17.0 或更高版本。 运行 az --version 即可查找版本。 如果需要进行安装或升级,请参阅安装 Azure CLI
  • Docker - 若要对注册表进行身份验证以拉取或推送映像,你需要安装一个本地 Docker。 Docker 提供适用于 macOSWindowsLinux 系统的安装说明。
  • 容器注册表 - 如果没有,请在你的 Azure 订阅中创建一个高级容器注册表,或升级现有注册表。 例如,使用 Azure 门户Azure CLI

创建令牌 - CLI

创建令牌并指定存储库

可使用 az acr token create 命令创建令牌。 创建令牌时,可以指定一个或多个存储库,并在每个存储库上指定关联的操作。 存储库不需要已在注册表中。 若要通过指定现有范围映射来创建令牌,请参阅下一部分

下面的示例在注册表 myregistry 中创建一个令牌,该令牌对 samples/hello-world 存储库具有以下权限:content/writecontent/read。 默认情况下,该命令会将默认令牌状态设置为 enabled,但你随时可以将状态更新为 disabled

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

输出会显示有关令牌的详细信息。 默认情况下,系统会生成两个不会过期的密码,但你可以根据需要设置过期日期。 建议将密码保存在安全的位置,以便以后将其用于身份验证。 无法再次检索这些密码,但可以生成新密码。

{
  "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"

备注

若要重新生成令牌密码和有效期,请参阅本文后面的重新生成令牌密码

输出包含该命令创建的范围映射的详细信息。 可以使用范围映射(在此处名为 MyToken-scope-map)将相同的存储库操作应用于其他令牌。 或者,稍后更新范围映射以更改关联的令牌的权限。

创建令牌并指定范围映射

创建令牌的另一种方法是指定现有的范围映射。 如果还没有范围映射,请先指定存储库和关联的操作来创建一个。 然后,在创建令牌时指定该范围映射。

若要创建范围映射,请使用 az acr scope-map create 命令。 以下命令创建的范围映射对前面使用的 samples/hello-world 存储库具有相同权限。

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 范围映射。 与前面的示例一样,该命令会将默认令牌状态设置为 enabled

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

输出会显示有关令牌的详细信息。 默认情况下,会生成两个密码。 建议将密码保存在安全的位置,以便以后将其用于身份验证。 无法再次检索这些密码,但可以生成新密码。

备注

若要重新生成令牌密码和有效期,请参阅本文后面的重新生成令牌密码

创建令牌 - 门户

你可以使用 Azure 门户来创建令牌和范围映射。 与 az acr token create CLI 命令一样,你可以应用现有的作范围映射,也可以在创建令牌时通过指定一个或多个存储库和关联的操作创建范围映射。 存储库暂时不需要在注册表中。

下面的示例创建了一个令牌和一个范围映射,后者具有对 samples/hello-world 存储库的以下权限:content/writecontent/read

  1. 在门户中,导航到容器注册表。

  2. 在“存储库权限”下,选择“令牌(预览)”>“+添加”。

    在门户中创建令牌

  3. 输入令牌名称。

  4. 在“范围映射”下,选择“新建” 。

  5. 配置范围映射:

    1. 为范围映射输入名称和说明。

    2. 在“存储库”下,输入 samples/hello-world,并在“权限”下,选择 content/readcontent/write 。 然后选择“+添加”。

      在门户中创建范围映射

    3. 添加存储库和权限后,选择“添加”,以添加范围映射。

  6. 接受默认令牌状态(“启用”),然后选择“创建” 。

验证并创建令牌后,令牌详细信息将显示在“令牌”屏幕中。

添加令牌密码

若要使用在门户中创建的令牌,必须生成密码。 你可以生成一个或两个密码,并为每个密码设置到期日期。

  1. 在门户中,导航到容器注册表。

  2. 在“存储库权限”下,选择“令牌(预览)”,然后选择一个令牌 。

  3. 在“令牌详细信息”中,选择“password1”或“password2”,然后选择“生成”图标 。

  4. 在“密码”屏幕上,根据需要为密码设置过期日期,并选择“生成”。 建议设置到期日期。

  5. 生成密码后,将其复制到一个安全的位置并保存。 关闭屏幕后无法检索生成的密码,但可以生成新的密码。

    在门户中创建令牌密码

使用令牌进行身份验证

当用户或服务使用令牌对目标注册表进行身份验证时,它会提供令牌名称作为用户名,以及生成的其中一个密码。

身份验证方法取决于已配置的操作或与令牌关联的操作。

操作 如何进行身份验证
content/delete Azure CLI 中的 az acr repository delete

示例: az acr repository delete --name myregistry --repository myrepo --username MyToken --password xxxxxxxxxx
content/read docker login

Azure CLI 中的 az acr login

示例: az acr login --name myregistry --username MyToken --password xxxxxxxxxx
content/write docker login

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

az acr repository show-tags

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

Azure CLI 中的 az acr repository update

示例:使用令牌

以下示例使用之前在本文中创建的令牌对存储库执行常见操作:推送和拉取映像、删除映像以及列出存储库标记。 该令牌最初设置有针对 samples/hello-world 存储库的推送权限(content/writecontent/read 操作)。

请求和标记测试映像

以下示例从 Azure 容器注册表拉取公共 hello-worldnginx 映像,并针对你的注册表和存储库标记它们。

docker pull mcr.azk8s.cn/hello-world
docker pull mcr.azk8s.cn/oss/nginx/nginx:1.15.5-alpine
docker tag mcr.azk8s.cn/hello-world myregistry.azurecr.cn/samples/hello-world:v1
docker tag mcr.azk8s.cn/oss/nginx/nginx:1.15.5-alpine myregistry.azurecr.cn/samples/nginx:v1

使用令牌进行身份验证

运行 docker loginaz acr login 以通过注册表进行身份验证,以便推送或拉取映像。 提供令牌名称作为用户名,并提供其密码之一。 令牌必须具有 Enabled 状态。

下面的示例针对 bash shell 进行了格式设置,并使用环境变量提供值。

TOKEN_NAME=MyToken
TOKEN_PWD=<token password>

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

输出应显示身份验证成功:

Login Succeeded

将映像推送到注册表

成功登录后,尝试将标记的映像推送到注册表。 由于该令牌有权将映像推送到 samples/hello-world 存储库,因此以下推送成功:

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

该令牌无权访问 samples/nginx 存储库,因此,以下推送尝试将失败,并显示类似于 requested access to the resource is denied 的错误:

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

更新令牌权限

若要更新令牌的权限,请更新相关联的范围映射中的权限。 更新的范围映射会立即应用于所有关联的令牌。

例如,使用对 samples/ngnx 存储库的 content/writecontent/read 操作更新 MyToken-scope-map,并删除对 samples/hello-world 存储库的 content/write 操作。

若要使用 Azure CLI,请运行 az acr scope map update 来更新范围映射:

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

在 Azure 门户中:

  1. 导航到容器注册表。
  2. 在“存储库权限”下,选择“范围映射(预览)”,然后选择要更新的范围映射 。
  3. 在“存储库”下,输入 samples/nginx,并在“权限”下,选择 content/readcontent/write 。 然后选择“+添加”。
  4. 在“存储库”下,选择 samples/hello-world,并在“权限”下,取消选择 content/write 。 再选择“保存”。

范围映射更新后,以下推送成功:

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

由于范围映射仅具有对 samples/hello-world 存储库的 content/read 权限,因此,对 samples/hello-world 存储库的推送尝试现在会失败:

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

从这两个存储库中提取映像将成功,因为范围映射提供对两个存储库的 content/read 权限:

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

删除映像

通过将 content/delete 操作添加到 nginx 存储库可以更新范围映射。 此操作允许删除存储库中的映像或删除整个存储库。

为简洁起见,我们只显示用于更新范围映射的 az acr scope map update 命令:

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

若要使用门户更新范围映射,请参阅上一部分

可使用以下 az acr repository delete 命令删除 samples/nginx 存储库。 若要删除映像或存储库,请将令牌的名称和密码传递给命令。 以下示例使用本文前面创建的环境变量:

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

显示存储库标记

metadata/read 操作添加到 hello-world 存储库可以更新范围映射。 此操作允许读取存储库中的清单和标记数据。

为简洁起见,我们只显示用于更新范围映射的 az acr scope map update 命令:

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

若要使用门户更新范围映射,请参阅上一部分

若要读取 samples/hello-world 存储库中的元数据,请运行 az acr repository show-manifestsaz acr repository show-tags 命令。

若要读取元数据,请将令牌的名称和密码传递给任一命令。 下面的示例使用之前在本文中创建的环境变量:

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

示例输出:

[
  "v1"
]

管理令牌和范围映射

列出范围映射

使用 az acr scope-map list 命令或门户中的“范围映射(预览)”屏幕,列出在注册表中配置的所有范围映射。 例如:

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

输出包括三个系统定义的范围映射和你生成的其他范围映射。 可以使用上述任一范围映射来配置令牌。

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

显示令牌详细信息

若要查看某个令牌的详细信息(例如其状态和密码到期日期),请运行 az acr token show 命令,或在门户中的“令牌(预览)”屏幕中选择该令牌。 例如:

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

使用门户中的 az acr token list 命令或“令牌(预览)”屏幕列出注册表中配置的所有令牌。 例如:

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

重新生成令牌密码

如果未生成令牌密码,或者要生成新密码,请运行 az acr token credential generate 命令。

下面的示例为 MyToken 令牌的 password1 生成新值,有效期为 30 天。 它将密码存储在环境变量 TOKEN_PWD 中。 此示例的格式是针对 bash shell 设置的。

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

要使用 Azure 门户生成令牌密码,请参阅本文前面的创建令牌 - 门户中的步骤。

使用新的范围映射更新令牌

如果要使用不同的范围映射来更新令牌,请运行 az acr token update 并指定新的范围映射。 例如:

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

在门户中的“令牌(预览)”屏幕上,选择相应令牌,然后在“范围映射”下,选择一个不同的范围映射 。

提示

使用新的范围映射更新令牌后,建议生成新的令牌密码。 请使用 az acr token credential 生成 命令或在 Azure 门户中重新生成令牌密码。

禁用或删除令牌

建议临时对用户或服务禁用令牌凭据。

使用 Azure CLI 运行 az acr token update 命令,将 status 设置为 disabled

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

在门户中的“令牌(预览)”屏幕中选择令牌,然后在“状态”下选择“禁用” 。

若要删除令牌以使利用其凭据的任何人的访问权限永久失效,请运行 az acr token delete 命令。

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

在门户中的“令牌(预览)”屏幕中选择令牌,然后选择“禁用” 。

后续步骤

  • 若要管理范围映射和令牌,请使用 az acr scope mapaz acr token 命令组中的其他命令。
  • 请参阅身份验证概述,了解对 Azure 容器注册表进行身份验证的其他选项,包括使用 Azure Active Directory 标识、服务主体或管理员帐户。