[Документация Yandex Cloud](../../../index.md) > [Yandex Identity and Access Management](../../index.md) > [Пошаговые инструкции](../index.md) > Федерации сервисных аккаунтов > Настройка федерации сервисных аккаунтов # Настройка федерации сервисных аккаунтов [Федерации сервисных аккаунтов](../../concepts/workload-identity.md) (Workload Identity Federation) позволяют настроить связь между внешними системами и Yandex Cloud по протоколу [OpenID Connect](https://openid.net/developers/how-connect-works/) (OIDC). За счет этого внешние системы могут выполнять действия с ресурсами Yandex Cloud от имени [сервисных аккаунтов](../../concepts/users/service-accounts.md) IAM без использования [авторизованных ключей](../../concepts/authorization/key.md). Это более безопасный способ, минимизирующий риск утечки учетных данных и возможность несанкционированного доступа. Чтобы настроить аутентификацию в API Yandex Cloud через федерацию сервисных аккаунтов: 1. [Подготовьте облако к работе](#prepare-cloud). 1. [Создайте федерацию сервисных аккаунтов](#create-wlif). 1. [Создайте привязку](#create-federated-credential). 1. [Обменяйте JWT-токен внешнего субъекта на IAM-токен сервисного аккаунта](#exchange-jwt-for-iam). Примеры настройки аутентификации для отдельных OIDC-провайдеров приведены в практических руководствах: * [GitHub](../../tutorials/wlif-github-integration.md). * [GitLab](../../tutorials/wlif-gitlab-integration.md). * [Пользовательская инсталляция Kubernetes](../../tutorials/wlif-k8s-integration.md). * [Managed Service for Kubernetes](../../tutorials/wlif-managed-k8s-integration.md). * [Настройка CI/CD между Cloud Functions и GitHub](../../tutorials/ci-cd-github-functions.md). ## Подготовьте облако к работе {#prepare-cloud} Зарегистрируйтесь в Yandex Cloud и создайте [платежный аккаунт](../../../billing/concepts/billing-account.md): 1. Перейдите в [консоль управления](https://console.yandex.cloud), затем войдите в Yandex Cloud или зарегистрируйтесь. 1. На странице **[Yandex Cloud Billing](https://center.yandex.cloud/billing/accounts)** убедитесь, что у вас подключен платежный аккаунт, и он находится в [статусе](../../../billing/concepts/billing-account-statuses.md) `ACTIVE` или `TRIAL_ACTIVE`. Если платежного аккаунта нет, [создайте его](../../../billing/quickstart/index.md) и [привяжите](../../../billing/operations/pin-cloud.md) к нему облако. Если у вас есть активный платежный аккаунт, вы можете создать или выбрать [каталог](../../../resource-manager/concepts/resources-hierarchy.md#folder), в котором будет работать ваша инфраструктура, на [странице облака](https://console.yandex.cloud/cloud). [Подробнее об облаках и каталогах](../../../resource-manager/concepts/resources-hierarchy.md). Для настройки федерации сервисных аккаунтов вам понадобится [сервисный аккаунт](../../concepts/users/service-accounts.md). Если у вас нет сервисного аккаунта, [создайте](../sa/create.md) его. ## Создайте федерацию сервисных аккаунтов {#create-wlif} {% note info %} Чтобы создать федерацию сервисных аккаунтов, пользователю необходима [роль](../../security/index.md#iam-workloadIdentityFederations-editor) `iam.workloadIdentityFederations.editor` или выше на каталог. {% endnote %} {% list tabs group=instructions %} - Консоль управления {#console} 1. В [консоли управления](https://console.yandex.cloud) на панели сверху нажмите ![image](../../../_assets/console-icons/layout-side-content-left.svg) или ![image](../../../_assets/console-icons/chevron-down.svg) и выберите каталог, в котором вы хотите создать федерацию сервисных аккаунтов. 1. В списке сервисов выберите **Identity and Access Management**. 1. На панели слева выберите ![cpus](../../../_assets/console-icons/cpus.svg) **Федерации сервисных аккаунтов**. 1. Нажмите **Создать федерацию** и в открывшейся форме: 1. В поле **Значение Issuer (iss)** введите URL OIDC-провайдера. Чтобы узнать это значение, обратитесь к документации или в службу технической поддержки используемого OIDC-провайдера. 1. В поле **Допустимые значения Audience (aud)** введите ресурс, для которого будет предназначен получаемый токен. Чтобы узнать это значение, обратитесь к документации или в службу технической поддержки используемого OIDC-провайдера. Вы можете задать одновременно несколько ресурсов-получателей IAM-токена. 1. В поле **Адрес JWKS** введите URL, по которому можно получить актуальный открытый ключ, выпущенный OIDC-провайдером и используемый для проверки подписи [JWT](https://ru.wikipedia.org/wiki/JSON_Web_Token). Чтобы узнать это значение, обратитесь к документации или в службу технической поддержки используемого OIDC-провайдера. 1. В поле **Имя** введите имя создаваемой федерации, например `sample-iam-federation`. 1. Нажмите кнопку **Создать**. - CLI {#cli} Если у вас еще нет интерфейса командной строки Yandex Cloud (CLI), [установите и инициализируйте его](../../../cli/quickstart.md#install). По умолчанию используется каталог, указанный при [создании](../../../cli/operations/profile/profile-create.md) профиля CLI. Чтобы изменить каталог по умолчанию, используйте команду `yc config set folder-id <идентификатор_каталога>`. Также для любой команды вы можете указать другой каталог с помощью параметров `--folder-name` или `--folder-id`. Если вы обращаетесь к ресурсу по имени, поиск будет выполнен в каталоге по умолчанию. Если вы обращаетесь к ресурсу по идентификатору, поиск будет выполнен глобально — во всех каталогах с учетом прав доступа. 1. Посмотрите описание команды создания федерации сервисных аккаунтов: ```bash yc iam workload-identity oidc federation create --help ``` 1. Создайте федерацию сервисных аккаунтов в каталоге по умолчанию: ```bash yc iam workload-identity oidc federation create \ --name <имя_федерации> \ --issuer "" \ --audiences "<ресурс_1>","<ресурс_2>",...,"<ресурс_n>" \ --jwks-url "<адрес_JWKS>" ``` Где: * `--name` — имя создаваемой федерации. Например: `sample-iam-federation`. Требования к имени: * длина — от 3 до 63 символов; * может содержать строчные буквы латинского алфавита, цифры и дефисы; * первый символ — буква, последний — не дефис. * `--issuer` — URL OIDC-провайдера. Чтобы узнать это значение, обратитесь к документации или в службу технической поддержки используемого OIDC-провайдера. * `--audiences` — ресурсы, для которых будет предназначен получаемый токен. Вы можете через запятую задать одновременно несколько ресурсов-получателей IAM-токена. Чтобы узнать это значение, обратитесь к документации или в службу технической поддержки используемого OIDC-провайдера. * `--jwks-url` — URL, по которому можно получить актуальный открытый ключ, выпущенный OIDC-провайдером и используемый для проверки подписи [JWT](https://ru.wikipedia.org/wiki/JSON_Web_Token). Чтобы узнать это значение, обратитесь к документации или в службу технической поддержки используемого OIDC-провайдера. Результат: ```text id: aje2c4qv19lf******** name: sample-iam-federation folder_id: b1gfq9pe6rd2******** enabled: true audiences: - https://gitlab.example.ru - https://gitlab.example.com issuer: https://gitlab.com jwks_url: https://gitlab.com/oauth/discovery/keys created_at: "2024-12-28T16:04:31.530652473Z" ``` Сохраните значение идентификатора созданной федерации сервисных аккаунтов, оно понадобится при создании привязки. Подробнее о команде `yc iam workload-identity oidc federation create` читайте в [справочнике CLI](../../../cli/cli-ref/iam/cli-ref/workload-identity/oidc/federation/create.md). - Terraform {#tf} [Terraform](https://www.terraform.io/) позволяет быстро создать облачную инфраструктуру в Yandex Cloud и управлять ею с помощью файлов конфигураций. В файлах конфигураций хранится описание инфраструктуры на языке HCL (HashiCorp Configuration Language). При изменении файлов конфигураций Terraform автоматически определяет, какая часть вашей конфигурации уже развернута, что следует добавить или удалить. Terraform распространяется под лицензией [Business Source License](https://github.com/hashicorp/terraform/blob/main/LICENSE), а [провайдер Yandex Cloud для Terraform](https://github.com/yandex-cloud/terraform-provider-yandex) — под лицензией [MPL-2.0](https://www.mozilla.org/en-US/MPL/2.0/). Подробная информация о ресурсах провайдера в документации на сайте [Terraform](https://www.terraform.io/docs/providers/yandex/index.html) или в [зеркале](../../../terraform/index.md). Если у вас еще нет Terraform, [установите его и настройте провайдер Yandex Cloud](../../../tutorials/infrastructure-management/terraform-quickstart.md#install-terraform). Чтобы управлять инфраструктурой с помощью Terraform от имени сервисного аккаунта или пользовательских аккаунтов: аккаунта на Яндексе, федеративного аккаунта и локального пользователя, [аутентифицируйтесь](../../../terraform/authentication.md) соответствующим способом. 1. Опишите в конфигурационном файле Terraform параметры федерации, которую необходимо создать: ```hcl resource "yandex_iam_workload_identity_oidc_federation" "wlif" { name = "<имя_федерации>" folder_id = "<идентификатор_каталога>" audiences = ["<ресурс_1>","<ресурс_2>",...,"<ресурс_n>"] issuer = "" jwks_url = "<адрес_JWKS>" } ``` Где: * `name` — имя создаваемой федерации. Например: `sample-iam-federation`. Требования к имени: * длина — от 3 до 63 символов; * может содержать строчные буквы латинского алфавита, цифры и дефисы; * первый символ — буква, последний — не дефис. * `folder_id` — [идентификатор](../../../resource-manager/operations/folder/get-id.md) каталога, в котором создается федерация сервисных аккаунтов. * `audiences` — ресурсы, для которых будет предназначен получаемый токен. Вы можете через запятую задать одновременно несколько ресурсов-получателей IAM-токена. Чтобы узнать это значение, обратитесь к документации или в службу технической поддержки используемого OIDC-провайдера. * `issuer` — URL OIDC-провайдера. Чтобы узнать это значение, обратитесь к документации или в службу технической поддержки используемого OIDC-провайдера. * `jwks_url` — URL, по которому можно получить актуальный открытый ключ, выпущенный OIDC-провайдером и используемый для проверки подписи [JWT](https://ru.wikipedia.org/wiki/JSON_Web_Token). Чтобы узнать это значение, обратитесь к документации или в службу технической поддержки используемого OIDC-провайдера. Подробнее о параметрах ресурса `yandex_iam_workload_identity_oidc_federation` в Terraform читайте в [документации провайдера](../../../terraform/resources/iam_workload_identity_oidc_federation.md). 1. Создайте ресурсы: 1. В терминале перейдите в директорию с конфигурационным файлом. 1. Проверьте корректность конфигурации с помощью команды: ```bash terraform validate ``` Если конфигурация является корректной, появится сообщение: ```bash Success! The configuration is valid. ``` 1. Выполните команду: ```bash terraform plan ``` В терминале будет выведен список ресурсов с параметрами. На этом этапе изменения не будут внесены. Если в конфигурации есть ошибки, Terraform на них укажет. 1. Примените изменения конфигурации: ```bash terraform apply ``` 1. Подтвердите изменения: введите в терминале слово `yes` и нажмите **Enter**. Terraform создаст федерацию сервисных аккаунтов. Убедиться в создании федерации можно в [консоли управления](https://console.yandex.cloud) или с помощью команды CLI: ```bash yc iam workload-identity oidc federation list ``` - API {#api} Чтобы создать федерацию сервисных аккаунтов, воспользуйтесь методом REST API [create](../../workload/oidc/workload-identity/api-ref/Federation/create.md) для ресурса [Federation](../../workload/oidc/workload-identity/api-ref/Federation/index.md) или вызовом gRPC API [FederationService/Create](../../workload/oidc/workload-identity/api-ref/grpc/Federation/create.md). {% endlist %} ## Создайте привязку {#create-federated-credential} {% note warning %} Привязка сервисных аккаунтов к федерациям сервисных аккаунтов может быть запрещена [политиками авторизации](../../concepts/access-control/access-policies.md) на уровне [каталога](../../../resource-manager/concepts/resources-hierarchy.md#folder), [облака](../../../resource-manager/concepts/resources-hierarchy.md#cloud) или [организации](../../../organization/concepts/organization.md). {% endnote %} Привязка — это связь, настроенная между федерацией сервисных аккаунтов, одним сервисным аккаунтом Yandex Cloud и одним внешним субъектом. Привязки необходимы для идентификации внешних субъектов в Yandex Identity and Access Management. {% note info %} Чтобы создать привязку, пользователю необходимы: * [роль](../../security/index.md#iam-serviceAccounts-federatedCredentialEditor) `iam.serviceAccounts.federatedCredentialEditor` или выше, выданная на сервисный аккаунт, который будет использоваться в привязке. * [роль](../../security/index.md#iam-workloadIdentityFederations-user) `iam.workloadIdentityFederations.user` или выше на каталог, в котором находится федерация сервисных аккаунтов. {% endnote %} {% list tabs group=instructions %} - Консоль управления {#console} 1. В [консоли управления](https://console.yandex.cloud) на панели сверху нажмите ![image](../../../_assets/console-icons/layout-side-content-left.svg) или ![image](../../../_assets/console-icons/chevron-down.svg) и выберите каталог, в котором находится сервисный аккаунт. При необходимости [создайте](../sa/create.md) новый сервисный аккаунт. 1. В списке сервисов выберите **Identity and Access Management**. 1. В списке выберите нужный сервисный аккаунт. 1. На верхней панели нажмите ![image](../../../_assets/console-icons/cpus.svg) **Привязать к федерации**. 1. В поле **Федерация сервисных аккаунтов** выберите ранее созданную федерацию. 1. В поле **Значение Subject (sub)** укажите идентификатор внешнего субъекта. Чтобы узнать это значение, обратитесь к документации или в службу технической поддержки используемого OIDC-провайдера. 1. Нажмите кнопку **Привязать**. - CLI {#cli} 1. Посмотрите описание команды создания привязки: ```bash yc iam workload-identity federated-credential create --help ``` 1. Создайте привязку, указав идентификатор нужного сервисного аккаунта: ```bash yc iam workload-identity federated-credential create \ --service-account-id <идентификатор_сервисного_аккаунта> \ --federation-id <идентификатор_федерации> \ --external-subject-id "<идентификатор_внешнего_субъекта>" ``` Где: * `--service-account-id` — [идентификатор](../sa/get-id.md) сервисного аккаунта Yandex Cloud. Сервисный аккаунт может быть расположен в каталоге, отличном от каталога федерации сервисных аккаунтов. * `--federation-id` — идентификатор федерации сервисных аккаунтов, полученный на предыдущем шаге. * `--external-subject-id` — идентификатор внешнего субъекта. Чтобы узнать это значение, обратитесь к документации или в службу технической поддержки используемого OIDC-провайдера. Результат: ```text id: aje401v1sup8******** service_account_id: ajek7v5j65cg******** federation_id: aje2c4qv19lf******** external_subject_id: project_path:root/test-iam-wlif:ref_type:branch:ref:master created_at: "2024-12-28T16:33:47.057632267Z" ``` Подробнее о команде `yc iam workload-identity federated-credential create` читайте в [справочнике CLI](../../../cli/cli-ref/iam/cli-ref/workload-identity/federated-credential/create.md). - Terraform {#tf} 1. Опишите в конфигурационном файле Terraform параметры привязки, которую необходимо создать: ```hcl resource "yandex_iam_workload_identity_federated_credential" "fc" { service_account_id = "<идентификатор_сервисного_аккаунта>" federation_id = "<идентификатор_федерации>" external_subject_id = "<идентификатор_внешнего_субъекта>" } ``` Где: * `service_account_id` — [идентификатор](../sa/get-id.md) сервисного аккаунта Yandex Cloud. Сервисный аккаунт может быть расположен в каталоге, отличном от каталога федерации сервисных аккаунтов. * `federation_id` — идентификатор федерации сервисных аккаунтов. * `external_subject_id` — идентификатор внешнего субъекта. Чтобы узнать это значение, обратитесь к документации или в службу технической поддержки используемого OIDC-провайдера. Подробнее о параметрах ресурса `yandex_iam_workload_identity_federated_credential` в Terraform читайте в [документации провайдера](../../../terraform/resources/iam_workload_identity_federated_credential.md). 1. Создайте ресурсы: 1. В терминале перейдите в директорию с конфигурационным файлом. 1. Проверьте корректность конфигурации с помощью команды: ```bash terraform validate ``` Если конфигурация является корректной, появится сообщение: ```bash Success! The configuration is valid. ``` 1. Выполните команду: ```bash terraform plan ``` В терминале будет выведен список ресурсов с параметрами. На этом этапе изменения не будут внесены. Если в конфигурации есть ошибки, Terraform на них укажет. 1. Примените изменения конфигурации: ```bash terraform apply ``` 1. Подтвердите изменения: введите в терминале слово `yes` и нажмите **Enter**. Terraform создаст указанную привязку. Убедиться в создании привязки для сервисного аккаунта можно в [консоли управления](https://console.yandex.cloud) или с помощью команды CLI: ```bash yc iam workload-identity federated-credential list \ --service-account-id <идентификатор_сервисного_аккаунта> ``` - API {#api} Чтобы создать привязку, воспользуйтесь методом REST API [create](../../workload/workload-identity/api-ref/FederatedCredential/create.md) для ресурса [FederatedCredential](../../workload/workload-identity/api-ref/FederatedCredential/index.md) или вызовом gRPC API [FederatedCredentialService/Create](../../workload/workload-identity/api-ref/grpc/FederatedCredential/create.md). {% endlist %} ## Обменяйте JWT-токен на IAM-токен сервисного аккаунта {#exchange-jwt-for-iam} Отправьте запрос к сервису обмена токенов Yandex Cloud: ```text POST https://auth.yandex.cloud/oauth/token HTTP/1.1 Content-Type: application/x-www-form-urlencoded grant_type=urn:ietf:params:oauth:grant-type:token-exchange& requested_token_type=urn:ietf:params:oauth:token-type:access_token& audience=<идентификатор_сервисного_аккаунта>& subject_token=& subject_token_type=urn:ietf:params:oauth:token-type:id_token ``` Где: * `grant_type` — тип запроса, имеет фиксированное значение `urn:ietf:params:oauth:grant-type:token-exchange`. * `requested_token_type` — тип запрашиваемого токена, имеет фиксированное значение `urn:ietf:params:oauth:token-type:access_token`. * `audience` — [идентификатор](../sa/get-id.md) сервисного аккаунта Yandex Cloud. * `subject_token` — JWT-токен внешнего субъекта. * `subject_token_type` — тип токена внешнего субъекта, имеет фиксированное значение `urn:ietf:params:oauth:token-type:id_token`. Результат: ```text HTTP/1.1 200 OK Content-Type: application/json { "access_token": "t1.9euelZqZlJyXlJGNno6JlIzGmsyUzO3rnpWazY6elMidm8-Nk8iPlZyZkJLl8_d_IUBE-e8AIgRS_d3z9z9QPUT57wAiBFL9zef1656Vmo2RyZqOm5KSj82KkZHNi5WL7_zN5_XrnpWaj46TnZvNksmNks2dj43MmJPv-MXrnpWajZHJmo6bkpKPzYqRkc2LlYu9656Vmp2PyJqYnprLk8aRxpqXzZbPteuGnNGWnpLRkI********************", "token_type": "Bearer", "expires_in": 43200 } ``` Где значение поля `access_token` — запрашиваемый IAM-токен сервисного аккаунта, который вы можете использовать для аутентификации при выполнении действий в [API Yandex Cloud](../../../api-design-guide/index.md). ## Полезные ссылки {#see-also} * [Федерации сервисных аккаунтов](../../concepts/workload-identity.md). * [Получение значения секрета Yandex Lockbox на стороне GitHub](../../tutorials/wlif-github-integration.md). * [Получение значения секрета Yandex Lockbox на стороне GitLab](../../tutorials/wlif-gitlab-integration.md).