Создание токена с разрешениями уровня репозитория

  • Статья

В этой статье описывается создание маркеров и область карт для управления доступом к репозиториям в реестре контейнеров. Создавая токены, владелец реестра может предоставлять пользователям или службам ограниченный по времени и области доступ к репозиториям, чтобы получать или отправлять образы или выполнять другие действия. Токен предоставляет более детализированные разрешения, чем другие варианты проверки подлинности в реестре, в которых областью действия разрешений является весь реестр.

Распространенные сценарии создания маркера:

  • Разрешить устройствам Интернета вещей с отдельными маркерами извлекать образ из репозитория.
  • Предоставьте внешней организации разрешения для пути репозитория.
  • Ограничение доступа к репозиторию для разных групп пользователей в организации. Например, вы можете предоставить доступ на запись и чтение тем разработчикам, которые создают образы, предназначенные для конкретных репозиториев, и доступ на чтение тем командам, которые выполняют развертывание из этих репозиториев.

Эта функция доступна во всех уровнях служб. Сведения о уровнях и ограничениях служб реестра см. в разделе Реестр контейнеров Azure уровнях служб

Ограничения

  • В настоящее время невозможно назначить разрешения на область репозитория удостоверениям Microsoft Entra, например субъекту-службе или управляемому удостоверению.

Основные понятия

Чтобы настроить разрешения на уровне репозитория, создайте токен со связанной картой области.

  • Токен вместе с созданным паролем позволяет пользователю пройти проверку подлинности в реестре. Вы можете задать дату истечения срока действия пароля токена или отключить токен в любое время.

    После проверки подлинности с помощью токена пользователь или служба могут выполнить одно действие или несколько в рамках области, охватывающей один репозиторий или несколько.

    Действие Описание Пример
    content/delete Удаление данных из репозитория Удаление репозитория или манифеста
    content/read Чтение данных из репозитория Извлечение артефакта
    content/write Запись данных в репозиторий Использование с content/read для отправки артефакта
    metadata/read Чтение метаданных из репозитория Перечисление тегов или манифестов
    metadata/write Запись метаданных в репозиторий Включение или отключение операций чтения, записи или удаления

Примечание.

Разрешения область репозитория не поддерживают возможность перечисления каталога всех репозиториев в реестре.

  • Область сопоставлять разрешения репозитория, которые применяются к маркеру, и могут повторно применяться к другим маркерам. Каждый токен связан с одной картой области. С помощью карты область можно:

    • Настройте несколько маркеров с одинаковыми разрешениями для набора репозиториев.
    • Обновите разрешения маркера при добавлении или удалении действий репозитория в карте область или применении другой карты область.

    Реестр контейнеров Azure также предоставляет несколько определяемых системой карт области, которые вы можете применить при создании токенов. Разрешения определяемых системой карт области применяются ко всем репозиториям в реестре. Количество отдельных действий соответствует ограничению количества репозиториев на карту области.

На следующем рисунке показана связь между токенами и картами области.

Registry tokens and scope maps

Необходимые компоненты

  • Примеры команд Azure CLI в этой статье требуют Azure CLI версии 2.17.0 или более поздней. Чтобы узнать версию, выполните команду az --version. Если вам необходимо выполнить установку или обновление, см. статью Установка Azure CLI 2.0.
  • Docker — чтобы проверить подлинность в реестре для извлечения или отправки образов, требуется локальная установка Docker. На сайте Docker предоставляются инструкции по установке для систем macOS, Windows и Linux.
  • Реестр контейнеров . Если у вас нет, создайте реестр контейнеров в подписке Azure. Это можно сделать на портале Azure или с помощью Azure 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 \

Важно!

Если правило дикого карта включает репозиторий, который еще не существует, разрешения дикого карта правила по-прежнему будут применяться к имени этого репозитория. Например, маркер, назначенный карте область, которая предоставляет [content/write, metadata/write] разрешения для sample/* репозиториев. Кроме того, предположим, что репозиторий sample/teamC/teamCimage еще не существует. Маркер будет иметь разрешения на отправку образов в репозиторий sample/teamC/teamCimage, что одновременно создаст репозиторий при успешной отправке.

Создание токена — портал

Для создания токенов и карт областей можно использовать портал Azure. Как и в случае с командой az acr token create интерфейса командной строки, можно применить существующую карту области или создать карту области при создании токена, указав один репозиторий или несколько и связанные действия. Репозитории не обязательно должны находиться в реестре.

Следующий пример создает токен и карту области со следующими разрешениями для репозитория samples/hello-world: content/write и content/read.

  1. На портале перейдите к нужному реестру контейнеров.

  2. В разделе "Разрешения репозитория" выберите "Маркеры> и добавить".

    Create token in portal

  3. Введите имя токена.

  4. В разделе Карта области выберите Создать.

  5. Настройте карту области.

    1. Введите имя и описание для карты области.

    2. В разделе Репозитории введите samples/hello-world и в разделе Разрешения выберите content/read и content/write. Затем выберите + Добавить.

      Create scope map in portal

    3. После добавления репозиториев и разрешений выберите Добавить, чтобы добавить карту области.

  6. Примите Состояние токена по умолчанию Включено, а затем выберите Создать.

После проверки и создания токена сведения о нем отображаются на экране Токены.

Добавление пароля токена

Чтобы использовать токен, созданный на портале, необходимо создать пароль. Можно создать один или два пароля и задать дату окончания срока действия для каждого из них. Новые пароли, созданные для токенов, доступны немедленно. Повторное создание новых паролей для токенов займет 60 секунд, прежде чем они будут реплицированы и станут доступными.

  1. На портале перейдите к нужному реестру контейнеров.

  2. В разделе "Разрешения репозитория" выберите "Маркеры" и выберите маркер.

  3. В сведениях о токене выберите password1 или password2 и щелкните значок "Создать".

  4. На экране пароля при необходимости задайте дату окончания срока действия пароля и выберите Создать. Мы рекомендуем задать дату окончания срока действия.

  5. После создания пароля скопируйте и сохраните его в надежном месте. После закрытия экрана вы не сможете повторно получить созданный пароль, но сможете создать новый.

    Create token password in portal

Проверка подлинности с помощью токена

Когда пользователь или служба используют токен для проверки подлинности в целевом реестре, они предоставляют имя пользователя и один из созданных паролей.

Метод проверки подлинности зависит от настроенных действий, связанных с токеном.

Действие Процедура проверки подлинности
content/delete az acr repository delete в Azure CLI

Пример: az acr repository delete --name myregistry --repository myrepo --username MyToken --password xxxxxxxxxx
content/read docker login

az acr login в Azure CLI

Пример: az acr login --name myregistry --username MyToken --password xxxxxxxxxx
content/write docker login

az acr login в Azure CLI
metadata/read az acr repository show

az acr repository show-tags

az acr manifest list-metadata в Azure CLI
metadata/write az acr repository untag

az acr repository update в Azure CLI

Примеры. Использование маркера

В следующих примерах токен, созданный ранее в этой статье, используется для выполнения общих операций с репозиторием: отправка и извлечение образов, удаление образов и перечисление тегов репозитория. Первоначально токен был настроен с разрешениями на передачу (действия content/write и content/read) для репозитория samples/hello-world.

Извлечение тестовых образов и пометка их тегами

В следующих примерах вам нужно извлечь общедоступные образы hello-world и nginx из Microsoft Container Registry и пометить их тегами для реестра и репозитория.

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

Обновление разрешений токена

Чтобы изменить разрешения токена, обновите разрешения в соответствующей карте области. Обновленная карта области применяется сразу для всех связанных токенов.

Например, обновите MyToken-scope-map с помощью действий content/write и content/read для репозитория samples/ngnx и удалите действие content/write для репозитория samples/hello-world.

Чтобы использовать 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/read и content/write. Затем выберите + Добавить.
  4. В разделе Репозитории выберите samples/hello-world и в разделе Разрешения отмените выбор content/write. Затем выберите Сохранить.

После обновления карты области следующая операция отправки выполняется успешно.

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

Так как карта области имеет разрешение content/read только для репозитория samples/hello-world, попытка отправки в репозиторий 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

Сведения об обновлении карты области с помощью портала см. в предыдущем разделе.

Чтобы удалить репозиторий samples/nginx, используйте следующую команду az acr repository delete. Чтобы удалить образы или репозитории, передайте имя и пароль токена в команду. В следующем примере используются переменные среды, созданные ранее в этой статье.

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 command.

Чтобы считать метаданные, передайте имя и пароль токена в любую из команд. В следующем примере используются переменные среды, созданные ранее в этой статье.

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

Образец вывода:

[
  "v1"
]

Управление токенами и картами области

Список карт области

Используйте команду az acr область-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 секунд, прежде чем они будут реплицированы и станут доступными.

Следующий пример создает новое значение для password1 для токена MyToken с периодом действия 30 дней. Пароль сохраняется в переменной среды TOKEN_PWD. Этот пример приведен в формате для оболочки Bash.

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, субъекта-службы или учетной записи администратора.
  • Сведения о подключенных реестрах и использовании токенов для доступа.