建立具有存放庫範圍權限的權杖

發行項
10/16/2024

本文說明如何建立權杖和範圍對應，以管理容器登錄中存放庫的存取權。藉由建立權杖，登錄擁有者可以提供具有限定範圍、限時存取存放庫的使用者或服務，以提取或推送映像，或執行其他動作。權杖提供較其他登錄驗證選項 (範圍是整個登錄的權限) 更加細微的權限。

建立權杖的常見案例包括：

允許具有個別權杖的 IoT 裝置從存放庫提取映像。
為外部組織提供存放庫路徑的權限。
為貴組織中的不同使用者群組限制存放庫存取權限。例如，為負責組建特定映像的開發人員提供寫入和讀取權限，而為從這些存放庫進行部署的群組提供讀取權限。

此功能適用於所有服務層級。如需登錄服務層級和限制的相關資訊，請參閱 Azure Container Registry 服務層級

限制

您目前無法將存放庫範圍的權限指派給 Microsoft Entra 身分識別，例如服務主體或受控識別。

概念

若要設定存放庫範圍的權限，您可以使用相關聯的範圍對應建立權杖。

權杖連同產生的密碼可讓使用者向登錄進行驗證。您可以設定權杖密碼的到期日，或隨時停用權杖。

使用權杖進行驗證之後，使用者或服務可以執行一或多個動作，範圍設定為一個或多個存放庫。

動作	描述	範例
`content/delete`	從存放庫移除資料	刪除存放庫或資訊清單
`content/read`	讀取來自存放庫的資料	提取成品
`content/write`	將資料寫入至存放庫	搭配 `content/read` 使用以推送成品
`metadata/read`	讀取來自存放庫的中繼資料	列出標籤或資訊清單
`metadata/write`	將中繼資料寫入至存放庫	啟用或停用讀取、寫入或刪除作業

注意

存放庫範圍的權限不支援列出登錄中所有存放庫的目錄。

範圍對應會將套用至權杖的存放庫權限分組，並可重新套用至其他權杖。每個權杖都與單一範圍對應相關聯。透過範圍對應，您可以：
- 使用與一組存放庫相同的權限來設定多個權杖。
- 在您新增或移除範圍對應中的存放庫動作，或套用不同的範圍對應時，更新權杖權限。
Azure Container Registry 也提供數個系統定義的範圍對應，您可以在建立權杖時套用。系統定義範圍對應的權限會套用至登錄中的所有存放庫。個別動作會對應至各範圍對應存放庫的限制。

下圖顯示權杖與範圍對應之間的關聯性。

登錄權杖和範圍對應

必要條件

Azure CLI - 本文中的 Azure CLI 命令範例需要 Azure CLI 2.17.0 版或更新版本。執行 az --version 以尋找版本。如果您需要安裝或升級，請參閱安裝 Azure CLI。
Docker - 若要向登錄進行驗證以提取或推送映像，您需要本機 Docker 安裝。 Docker 提供 macOS、Windows 和 Linux 系統的安裝指示。
容器登錄 - 如果您沒有容器登錄，請在您的 Azure 訂用帳戶中建立一個容器登錄。例如，使用 Azure 入口網站或 Azure CLI。

建立權杖 - CLI

建立權杖並指定存放庫

使用 az acr Token create 命令來建立權杖。建立權杖時，您可以在每個存放庫上指定一個或多個存放庫和相關聯的動作。存放庫還不需要在登錄中。若要指定現有的範圍對應來建立權杖，請參閱下一節。

下列範例會在登錄 myregistry 中使用 samples/hello-world 存放庫的下列權限建立權杖：content/write 和 content/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

輸出會顯示權杖的詳細資料。依預設會產生兩個密碼。建議您將密碼儲存在安全的位置，以供稍後用來進行驗證。系統無法再次擷取密碼，但可以產生新的密碼。

注意

若要重新產生權杖密碼和到期期間，請參閱本文稍後說明的重新產生權杖密碼。

如何使用範圍對應來定義及指派多個存放庫的權限

範圍對應允許使用萬用字元，為共用一般前置詞的多個存放庫定義並授與類似的權限。具有特定權限的存放庫、具有萬用字元的存放庫也可以在相同的範圍對應中使用。這可讓您彈性地管理單一範圍對應中多個存放庫集的權限。

建立範圍對應並指派給權杖時，可以建立存放庫權限。或者，也可以建立權杖並直接指派給存放庫。

下列範例會建立具有萬用字元的範圍對應，然後將它指派給權杖。

az acr scope-map create --name MyScopeMapWildcard --registry myregistry \
  --repository samples/* \
  content/write content/read \
  --description "Sample scope map with wildcards"
az acr token create --name MyTokenWildcard \
  --registry myregistry \
  --scope-map MyScopeMapWildcard

下列範例會建立具有萬用字元的權杖。

 az acr token create --name MyTokenWildcard --registry myregistry \
  --repository samples/* \
  content/write content/read \

萬用字元權限是附加的，這表示當存取特定存放庫時，產生的權限會包含符合萬用字元前置詞之所有範圍對應規則的權限。

在此範例中，範圍對應會定義三種不同類型存放庫的權限：

存放庫	權限
`sample/*`	`content/read`
`sample/teamA/*`	`content/write`
`sample/teamA/projectB`	`content/delete`

該權杖被指派了一個範圍對應，以授與 [content/read, content/write, content/delete] 權限來存取存放庫 sample/teamA/projectB。不過，當使用相同的權杖來存取 sample/teamA/projectC 存放庫時，它只有 [content/read, content/write] 權限。

重要

在範圍對應中使用萬用字元的存放庫應該一律以 /* 尾碼結尾才有效，且存放庫名稱中具有單一萬用字元。以下是無效萬用字元的一些範例：

sample/*/teamA 在存放庫名稱中間有萬用字元。
具有萬用字元的 sample/teamA* 未以 `/*`` 結尾。
sample/teamA/*/projectB/* 在存放庫名稱中具有多個萬用字元。

根層級萬用字元

萬用字元也可以在根層級套用。這表示指派給定義為 * 存放庫的任何權限都將在登錄範圍內套用。

以下範例示範如何建立具有根層級萬用字元的權杖，這將授與該權杖具有對登錄中的所有存放庫的 [content/read, content/write] 權限。這提供了一個向登錄中的所有存放庫授與權限的簡單方法，而無需個別指定每個存放庫。

 az acr token create --name MyTokenWildcard --registry myregistry \
  --repository * \
  content/write content/read \

重要

如果萬用字元規則包含尚未存在的存放庫，則萬用字元規則的權限仍會套用至該存放庫名稱。例如，指派給範圍對應的權杖為 sample/* 存放庫授與 [content/write, metadata/write] 權限。此外，假設存放庫 sample/teamC/teamCimage 還不存在。該權杖將有權將映像推送到存放庫 sample/teamC/teamCimage，這將在成功推送時同時建立該存放庫。

建立權杖 - 入口網站

您可以使用 Azure 入口網站來建立權杖和範圍對應。和使用 az acr token create CLI 命令一樣，您可以套用現有的範圍對應，或藉由指定一個或多個存放庫和相關聯的動作，在建立權杖時建立範圍對應。存放庫還不需要在登錄中。

下列範例會建立權杖，並在 samples/hello-world 存放庫上建立具有下列權限的範圍對應：content/write 和 content/read。

在入口網站中，瀏覽至容器登錄。
在 [存放庫權限] 底下，選取 [權杖] > [+新增]。
輸入權杖名稱。
在 [範圍對應] 底下，選取 [新建]。
設定範圍對應：
1. 輸入範圍對應的名稱及描述。
2. 在 [存放庫] 下，輸入 samples/hello-world，然後在 [權限] 底下，選取 [content/read] 和 [content/write]。然後選取 [+新增]。
3. 新增存放庫和權限之後，請選取 [新增] 以新增範圍對應。
接受 [已啟用] 的預設權杖狀態，然後選取 [建立]。

驗證並建立權杖之後，權杖詳細資料會出現在 [權杖] 畫面中。

新增權杖密碼

若要使用在入口網站中建立的權杖，您必須產生密碼。您可以產生一或兩組密碼，並為每組密碼設定一個到期日。針對權杖建立的新密碼可以立即使用。重新產生權杖的新密碼需要 60 秒進行複寫和提供使用。

在入口網站中，瀏覽至容器登錄。
在 [存放庫權限] 底下，選取 [權杖]，再選取權杖。
在權杖詳細資料中，選取 [password1] 或 [password2]，然後選取 [產生] 圖示。
在 [密碼] 畫面中，選擇設定密碼的到期日，然後選取 [產生]。建議您設定到期日。
產生密碼之後，請複製密碼並儲存到安全的位置。您無法在關閉畫面後取出產生的密碼，但您可以產生新的密碼。

使用權杖進行驗證

使用者或服務使用權杖向目標登錄進行驗證時，目標登錄會提供權杖名稱做為使用者名稱和其中一個產生的密碼。

驗證方法取決於已設定的動作或與權杖相關聯的動作。

動作	如何驗證
`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 manifest list-metadata`
`metadata/write`	`az acr repository untag` 在 Azure CLI 中的 `az acr repository update`

範例：使用權杖

下列範例會使用本文稍早建立的權杖執行存放庫的一般作業：推送和提取映像、刪除映像，以及列出存放庫標籤。此權杖一開始是以 samples/hello-world 存放庫上的推送權限 (content/write 和 content/read 動作) 設定。

提取和標記測試影像

針對下列範例，請從 Microsoft Container Registry 提取 hello-world 和 nginx 映像，然後標記映像以用於您的登錄和存放庫。

docker pull mcr.microsoft.com/hello-world
docker pull mcr.microsoft.com/oss/nginx/nginx:1.15.5-alpine
docker tag mcr.microsoft.com/hello-world myregistry.azurecr.io/samples/hello-world:v1
docker tag mcr.microsoft.com/oss/nginx/nginx:1.15.5-alpine myregistry.azurecr.io/samples/nginx:v1

使用權杖進行驗證

執行 docker login 或 az acr login 以使用登錄進行驗證，推送或提取映像。提供權杖名稱作為使用者名稱，並提供其中一個密碼。權杖必須具有 Enabled 狀態。

下列範例會針對 Bash 殼層進行格式化，並使用環境變數來提供值。

TOKEN_NAME=MyToken
TOKEN_PWD=<token password>

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

輸出應該會顯示成功的驗證：

Login Succeeded

將映像推送到登錄

成功登入之後，嘗試將標記的映像推送至登錄。因為權杖具有將映像推送至 samples/hello-world 存放庫的權限，所以下列推送會成功：

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

權杖沒有 samples/nginx 存放庫的權限，因此下列的推送嘗試會失敗，並出現類似 requested access to the resource is denied的錯誤：

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

更新權杖權限

若要更新權杖的權限，請更新相關聯範圍對應中的權限。更新的範圍對應會立即套用至所有相關聯的權杖。

例如，使用 samples/ngnx 存放庫上的 content/write 和 content/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 入口網站中：

瀏覽至您的容器登錄。
在 [存放庫權限] 底下，選取 [範圍對應]，然後選取要更新的範圍對應。
在 [存放庫] 下，輸入 samples/nginx，然後在 [權限] 底下，選取 [content/read] 和 [content/write]。然後選取 [+新增]。
在 [存放庫] 底下，選取 [samples/hello-world]，然後在 [權限] 下，取消選取 content/write。然後選取儲存。

更新範圍對應之後，下列推送會成功：

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

因為範圍對應只有 samples/hello-world 存放庫的 content/read 權限，所以對 samples/hello-world 存放庫的推送嘗試目前會失敗：

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

從這兩個存放庫提取映像都會成功，因為範圍對應會提供這兩個存放庫的 content/read 權限：

docker pull myregistry.azurecr.io/samples/nginx:v1
docker pull myregistry.azurecr.io/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 manifest list-metadata 或 az 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 命令。重新產生權杖的新密碼需要 60 秒進行複寫和提供使用。

下列範例會針對 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 generate 命令，或在 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-map 和 az acr Token 命令群組中的其他命令。
如需向 Azure 容器登錄進行驗證的其他選項，包括使用 Microsoft Entra 身分識別、服務主體或系統管理員帳戶，請參閱驗證概觀。
了解已連線的登錄和使用權杖進行存取。

共用方式為

建立具有存放庫範圍權限的權杖

限制

概念

必要條件

建立權杖 - CLI

建立權杖並指定存放庫

建立權杖並指定範圍對應

如何使用範圍對應來定義及指派多個存放庫的權限

根層級萬用字元

建立權杖 - 入口網站

新增權杖密碼

使用權杖進行驗證

範例：使用權杖

提取和標記測試影像

使用權杖進行驗證

將映像推送到登錄

更新權杖權限

刪除映像

顯示存放庫標籤

管理權杖和範圍對應

列出範圍對應

顯示權杖詳細資料

重新產生權杖密碼

使用新的範圍對應更新權杖

停用或刪除權杖

下一步

意見反應

其他資源