Связаться с намиПодключиться

Федерации сервисных аккаунтов

Статья создана
Обновлена 15 мая 2025 г.

Федерация сервисных аккаунтов (Workload Identity Federation) — это инструмент Yandex Identity and Access Management, позволяющий настроить процесс обмена токенов любой системы, совместимой с протоколом OpenID Connect, на IAM-токены, которые можно использовать для обращения к API Yandex Cloud.

Популярные варианты использования этого инструмента:

  • Запрос пода Kubernetes к API Yandex Cloud для получения содержимого секрета Yandex Lockbox.
  • Запрос к API Yandex Cloud из CI/CD системы, такой как GitLab, для развертывания облачных сервисов с помощью Terraform.

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

Подробнее о протоколе OpenID Connect см. в спецификации OIDC.

Настроить федерацию сервисных аккаунтов можно в консоли управления или с помощью Yandex Cloud CLI.

Чтобы создать федерацию сервисных аккаунтов, необходима роль iam.workloadIdentityFederations.editor или выше.

Схема работы федерации

Федерация сервисных аккаунтов создается в каталоге и требует настройки обязательных параметров совместимого с OpenID Connect провайдера (OIDC-провайдера):

  • audience — ресурс, для которого будет предназначен выданный IAM-токен. Передается в формате StringOrURI.

    Для одной федерации может быть задано как одно, так и целый массив значений audience.

  • issuer — URL сервера OIDC-провайдера.

  • jwks-url — URL, по которому можно получить актуальный открытый ключ, выпущенный OIDC-провайдером и используемый для проверки подписи JWT.

В одном каталоге можно создать несколько федераций сервисных аккаунтов.

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

Внешний субъект — это авторизованный у стороннего OIDС-провайдера субъект внешнего по отношению к Yandex Cloud сервиса, которому требуется получить IAM-токен Yandex Cloud. Например, это может быть сервисный аккаунт Kubernetes или задание GitLab.

Этапы получения IAM-токена с помощью сервисного аккаунта, привязанного к федерации:

  1. При необходимости получить IAM-токен Yandex Cloud внешний субъект обращается к OIDС-провайдеру, который на своей стороне выпускает для него JWT-токен.
  2. Внешний субъект передает полученный JWT-токен в федерацию сервисных аккаунтов Identity and Access Management.
  3. Сервис Identity and Access Management проверяет полномочия внешнего субъекта (по наличию подходящей привязки) и действительность переданного JWT-токена (с помощью публичного ключа).
  4. Если полномочия подтверждены, а JWT-токен действителен, Identity and Access Management обменивает этот JWT-токен на IAM-токен сервисного аккаунта Yandex Cloud, связанного с этим внешним субъектом в соответствующей привязке.
  5. Внешний субъект выполняет необходимые запросы к API Yandex Cloud с помощью полученного IAM-токена от имени заданного в привязке сервисного аккаунта.

Обменять JWT-токен внешнего субъекта на IAM-токен сервисного аккаунта можно с помощью POST-запроса к эндпоинту https://auth.yandex.cloud/oauth/token.

Привязки в федерации

Привязка — это связь, настроенная между федерацией сервисных аккаунтов, одним сервисным аккаунтом Yandex Cloud и одним внешним субъектом.

Привязка создается в федерации удостоверений и требует настройки обязательных параметров:

  • Идентификатор или имя сервисного аккаунта — данные сервисного аккаунта, для которого будет выдаваться IAM-токен при запросе от внешнего субъекта.

    Сервисный аккаунт может быть расположен в каталоге, отличном от каталога федерации сервисных аккаунтов (только при создании привязки через CLI, Terraform или API).

    Сервисному аккаунту должны быть назначены роли, предоставляющие разрешения на выполнение необходимых действий с ресурсами или данными в Yandex Cloud.

  • Идентификатор федерации сервисных аккаунтов — данные федерации сервисных аккаунтов, для которой добавляется привязка.

  • subject — идентификатор, присвоенный OIDС-провайдером внешнему субъекту, выполняющему запрос к API Yandex Cloud.

Создать привязку можно с помощью CLI.

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

  • роль iam.serviceAccounts.federatedCredentialEditor или выше, выданная на сервисный аккаунт, который будет использоваться в привязке.
  • роль iam.workloadIdentityFederations.user или выше на каталог, в котором находится нужная федерация сервисных аккаунтов.

Примеры использования

Предыдущая
Федерации удостоверений
Следующая
Квоты и лимиты