Аутентификация в реестре контейнеров Azure с помощью субъектов-служб

  • Статья

Вы можете использовать субъект-службу Microsoft Entra для предоставления принудительной отправки, извлечения или другого доступа к реестру контейнеров. Субъект-служба позволяет предоставлять автоматический доступ к службам и приложениям.

Что такое субъект-служба?

Субъекты-службы идентификатора Microsoft Entra предоставляют доступ к ресурсам Azure в вашей подписке. Их можно считать пользователями, представляющими конкретную службу. Слово "служба" здесь имеет широкое значение и включает любое приложение, службу или платформу, которым нужен доступ к ресурсам. Субъекту-службе можно присвоить права доступа, ограниченные конкретными ресурсами. После этого вам останется лишь настроить применение этого субъекта-службы для доступа к ресурсам из приложения или службы.

В контексте Реестр контейнеров Azure можно создать субъект-службу Microsoft Entra с помощью извлечения, отправки и извлечения или других разрешений для частного реестра в Azure. Полный список см. в статье, посвященной ролям и разрешениям реестра контейнеров Azure.

Почему именно субъект-служба?

Используя субъект-службу Microsoft Entra, вы можете предоставить область доступ к частному реестру контейнеров. Для каждого приложении и для каждой службы можно создать отдельный субъект-службу и настроить для каждого из них правильные права доступа к реестру. Кроме того, вы сможете в любой момент легко изменить реквизиты или отменить доступ для каждого конкретного субъекта-службы, поскольку его учетные данные применяются только в одном приложении или службе.

Например, для веб-приложения можно настроить субъект-службу только с правами pull для образа, а для системы разработки — другой субъект-службу с правами доступа push и pull. Если в будущем вам придется передать разработку приложения другим сотрудникам, вы сможете просто заменить учетные данные первого субъекта-службы, ничего не изменяя в системе разработки.

Когда следует использовать субъект-службу

Субъект-службы следует очень удобны для предоставления доступа к реестру при работе со сценариями с автоматическим доступом. Это позволяет приложениям, службам и (или) скриптам передавать или получать образы контейнеров в полностью автоматическом режиме или без участия оператора. Например:

  • Извлечение: развертывание контейнеров из реестра в системы оркестрации, в том числе Kubernetes, DC/OS и Docker Swarm. Вы также можете извлекать из реестров контейнеров связанные службы Azure, такие как Служба приложений, пакетная служба, Service Fabric и другие.

    Совет

    В некоторых сценариях Kubernetes для извлечения образов из реестра контейнеров Azure рекомендуется использовать субъект-службу. С помощью Службы Azure Kubernetes (AKS) можно также использовать автоматизированный механизм для проверки подлинности в целевом реестре, включив управляемое удостоверение кластера.

    • Отправка: создание образов контейнеров и их отправка в решения непрерывной интеграции и развертывания (например, Azure Pipelines или Jenkins).

Для отдельного доступа к реестру, например при ручном извлечении образа контейнера на рабочую станцию разработки, рекомендуется использовать собственное удостоверение Microsoft Entra вместо доступа к реестру (например, az acr login).

Создание субъекта-службы

Чтобы создать субъект-службу с доступом к реестру контейнеров, выполните следующий скрипт в Azure Cloud Shell или локальную установку Azure CLI. Скрипт отформатирован для оболочки Bash.

Перед выполнением сценария обновите переменную ACR_NAME с именем реестра контейнеров. Значение SERVICE_PRINCIPAL_NAME должно быть уникальным в клиенте Microsoft Entra. Если вы получаете ошибку "'http://acr-service-principal' already exists.", укажите другое имя для субъекта-службы.

Можно изменять значение --role в команде az ad sp create-for-rbac, если необходимо предоставить другие разрешения. Полный список ролей см. в разделе Роли и разрешения реестра контейнеров Azure.

После запуска скрипта запишите идентификатор и пароль субъекта-службы. Сохранив эти учетные данные, вы можете настроить приложения и службы для аутентификации в качестве субъектов-служб в реестре контейнеров.

#!/bin/bash
# This script requires Azure CLI version 2.25.0 or later. Check version with `az --version`.

# Modify for your environment.
# ACR_NAME: The name of your Azure Container Registry
# SERVICE_PRINCIPAL_NAME: Must be unique within your AD tenant
ACR_NAME=$containerRegistry
SERVICE_PRINCIPAL_NAME=$servicePrincipal

# Obtain the full registry ID
ACR_REGISTRY_ID=$(az acr show --name $ACR_NAME --query "id" --output tsv)
# echo $registryId

# Create the service principal with rights scoped to the registry.
# Default permissions are for docker pull access. Modify the '--role'
# argument value as desired:
# acrpull:     pull only
# acrpush:     push and pull
# owner:       push, pull, and assign roles
PASSWORD=$(az ad sp create-for-rbac --name $SERVICE_PRINCIPAL_NAME --scopes $ACR_REGISTRY_ID --role acrpull --query "password" --output tsv)
USER_NAME=$(az ad sp list --display-name $SERVICE_PRINCIPAL_NAME --query "[].appId" --output tsv)

# Output the service principal's credentials; use these in your services and
# applications to authenticate to the container registry.
echo "Service principal ID: $USER_NAME"
echo "Service principal password: $PASSWORD"

Использование существующего субъекта-службы

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

В следующем скрипте используется команда az role assignment create, чтобы предоставить разрешения на извлечение субъекту-службе, указанному в переменной SERVICE_PRINCIPAL_ID. Измените значение --role, если нужно предоставить другой уровень доступа.

#!/bin/bash
# Modify for your environment. The ACR_NAME is the name of your Azure Container
# Registry, and the SERVICE_PRINCIPAL_ID is the service principal's 'appId' or
# one of its 'servicePrincipalNames' values.
ACR_NAME=$containerRegistry
SERVICE_PRINCIPAL_ID=$servicePrincipal

# Populate value required for subsequent command args
ACR_REGISTRY_ID=$(az acr show --name $ACR_NAME --query id --output tsv)

# Assign the desired role to the service principal. Modify the '--role' argument
# value as desired:
# acrpull:     pull only
# acrpush:     push and pull
# owner:       push, pull, and assign roles
az role assignment create --assignee $SERVICE_PRINCIPAL_ID --scope $ACR_REGISTRY_ID --role acrpull

Примеры сценариев

На GitHub можно найти предыдущие примеры сценариев для Azure CLI, а также версии для Azure PowerShell:

Проверка подлинности с помощью субъекта-службы

Создав субъект-службу и предоставив ему доступ к реестру контейнеров, вы сможете настроить его учетные данные для доступа к автономным приложениям и службам или использовать для входа команду docker login. Используйте следующие значения.

  • Имя пользователя — идентификатор приложения субъекта-службы (клиент)
  • Password — пароль (секрет клиента) субъекта-службы

Значение имени пользователя имеет формат xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Совет

Можно повторно создать пароль (секрет клиента) субъекта-службы, выполнив команду az ad sp credential reset.

Использование учетных данных со службами Azure

Учетные данные субъекта-службы можно использовать из любой службы Azure, которая может выполнить проверку подлинности в реестре контейнеров Azure. Вы можете использовать учетные данные субъекта-службы вместо учетных данных администратора реестра в различных сценариях.

Использование входа Docker

С помощью субъекта-службы можно запустить docker login. В примере ниже идентификатор приложения субъекта-службы будет передан в переменной среды $SP_APP_ID, а пароль — в переменной $SP_PASSWD. Современные рекомендации по управлению учетными данными Docker см. в справочных материалах по команде docker login.

# Log in to Docker with service principal credentials
docker login myregistry.azurecr.io --username $SP_APP_ID --password $SP_PASSWD

После входа в систему Docker кэширует учетные данные.

Использование с сертификатом

Если вы добавили сертификат в субъект-службу, вы можете войти в Azure CLI с проверкой подлинности на основе сертификатов, а затем использовать команду az acr login для доступа к реестру. Использование сертификата в качестве секрета вместо пароля повышает защиту при работе в интерфейсе командной строки.

При создании субъекта-службы может быть создан самозаверяющий сертификат. Кроме того, можно добавить один или несколько сертификатов в существующий субъект-службу. Например, если вы используете один из скриптов, описанных в этой статье, чтобы создать или обновить субъект-службу с правами на извлечение или отправку образов из реестра, добавьте сертификат с помощью команды az ad sp credential reset.

Чтобы использовать субъект-службу с сертификатом для входа в Azure CLI, сертификат должен быть в формате PEM и включать закрытый ключ. Если ваш сертификат не имеет нужного формата, используйте для его преобразования средство наподобие openssl. При выполнении команды az login для входа в CLI с помощью субъекта-службы также укажите идентификатор приложения субъекта-службы и идентификатор арендатора Active Directory. В примере ниже эти значения показаны как переменные среды:

az login --service-principal --username $SP_APP_ID --tenant $SP_TENANT_ID  --password /path/to/cert/pem/file

Затем запустите команду az acr login для проверки подлинности в реестре:

az acr login --name myregistry

Интерфейс командной строки использует маркер, созданный при выполнении команды az login, для аутентификации вашего сеанса в реестре.

Создание субъекта-службы для межклиентских сценариев

Субъект-служба также может использоваться в сценариях Azure, требующих извлечения образов из реестра контейнеров в одном идентификаторе Microsoft Entra (клиенте) в службу или приложение в другом. Например, организация может запустить приложение в клиенте A, для которого необходимо извлекать образы из общего реестра контейнеров в клиенте B.

Чтобы создать субъект-службу, которая может выполнять проверку подлинности с помощью реестра контейнеров в межклиентском сценарии, выполните приведенные ниже действия.

  • Создайте мультитенантное приложение (субъект-службу) в клиенте A.
  • Подготовьте это приложение в клиенте B.
  • Предоставьте субъекту-службы разрешения для извлечения образов из реестра в клиенте B.
  • Обновите службу или приложение в клиенте A для обеспечения проверки подлинности с помощью нового субъекта-службы.

Пример с инструкциями см. в статье Извлечение образов из реестра контейнеров в кластер AKS в другом клиенте AD.

Возобновление действия субъекта-службы

Субъект-служба создается со сроком действия в один год. Вы можете продлить действие на срок более одного года или указать дату окончания срока действия с помощью команды az ad sp credential reset.

Следующие шаги