[Yandex Cloud documentation](../../../index.md) > [Yandex Identity and Access Management](../../index.md) > [Step-by-step guides](../index.md) > Workload identity federations > Setting up workload identity federations

# Setting up workload identity federations

[Workload identity federations](../../concepts/workload-identity.md) allow you to configure a link between external systems and Yandex Cloud via the [OpenID Connect](https://openid.net/developers/how-connect-works/) (OIDC) protocol. This allows external systems to perform actions with Yandex Cloud resources under IAM [service accounts](../../concepts/users/service-accounts.md) without using [authorized keys](../../concepts/authorization/key.md). This is a more secure method that minimizes the risk of credential leakage and the possibility of unauthorized access.

To set up authentication in the Yandex Cloud API via a workload identity federation:

1. [Get your cloud ready](#prepare-cloud).
1. [Create a workload identity federation](#create-wlif).
1. [Create federated credentials](#create-federated-credential).
1. [Exchange a JWT of an external subject for a service account IAM token](#exchange-jwt-for-iam).

For examples of setting up authentication for specific OIDC providers, see these tutorials:

* [GitHub](../../tutorials/wlif-github-integration.md).
* [GitLab](../../tutorials/wlif-gitlab-integration.md).
* [Custom Kubernetes installation](../../tutorials/wlif-k8s-integration.md).
* [Managed Service for Kubernetes](../../tutorials/wlif-managed-k8s-integration.md).
* [Configuring CI/CD between Cloud Functions and GitHub](../../tutorials/ci-cd-github-functions.md).

## Get your cloud ready {#prepare-cloud}

Sign up for Yandex Cloud and create a [billing account](../../../billing/concepts/billing-account.md):
1. Navigate to the [management console](https://console.yandex.cloud) and log in to Yandex Cloud or create a new account.
1. On the **[Yandex Cloud Billing](https://center.yandex.cloud/billing/accounts)** page, make sure you have a billing account linked and it has the `ACTIVE` or `TRIAL_ACTIVE` [status](../../../billing/concepts/billing-account-statuses.md). If you do not have a billing account, [create one](../../../billing/quickstart/index.md) and [link](../../../billing/operations/pin-cloud.md) a cloud to it.

If you have an active billing account, you can create or select a [folder](../../../resource-manager/concepts/resources-hierarchy.md#folder) for your infrastructure on the [cloud page](https://console.yandex.cloud/cloud).

[Learn more about clouds and folders here](../../../resource-manager/concepts/resources-hierarchy.md).

To set up a workload identity federation, you need a [service account](../../concepts/users/service-accounts.md). If you do not have a service account, [create](../sa/create.md) one.

## Create a workload identity federation {#create-wlif}

{% note info %}

To create a workload identity federation, the user needs the `iam.workloadIdentityFederations.editor` [role](../../security/index.md#iam-workloadIdentityFederations-editor) or higher for the folder.

{% endnote %}

{% list tabs group=instructions %}

- Management console {#console}

  1. In the [management console](https://console.yandex.cloud), click ![image](../../../_assets/console-icons/layout-side-content-left.svg) or ![image](../../../_assets/console-icons/chevron-down.svg) in the top panel and select the folder where you want to create a workload identity federation.
  1. In the list of services, select **Identity and Access Management**.
  1. In the left-hand panel, select ![cpus](../../../_assets/console-icons/cpus.svg) **Workload identity federations**.
  1. Click **Create federation** and in the form that opens, proceed as follows:
      1. In the **Issuer value (iss)** field, enter the OIDC provider's URL.

          To get this value, refer to the OIDC provider's documentation or contact their support.
      1. In the **Acceptable Audience values (AUD)** field, specify the resource for which the token will be issued.

          To get this value, refer to the OIDC provider's documentation or contact their support.

          You can specify multiple resources to issue the IAM token for.
      1. In the **JWKS address** field, specify the URL for retrieving the current public key issued by the OIDC provider and used for [JWT](https://en.wikipedia.org/wiki/JSON_Web_Token) signature verification.

          To get this value, refer to the OIDC provider's documentation or contact their support.
      1. In the **Name** field, enter a name for the new federation, e.g., `sample-iam-federation`.
      1. Click **Create**.

- CLI {#cli}

  If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../../cli/quickstart.md#install).

  The folder used by default is the one specified when [creating](../../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id <folder_ID>` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

  1. View the description of the command for creating a workload identity federation:

      ```bash
      yc iam workload-identity oidc federation create --help
      ```

  1. Create a workload identity federation in the default folder:

      ```bash
      yc iam workload-identity oidc federation create \
        --name <federation_name> \
        --issuer "<OIDC_provider_URL>" \
        --audiences "<resource_1>","<resource_2>",...,"<resource_n>" \
        --jwks-url "<JWKS_address>"
      ```

      Where:

      * `--name`: Name of the new federation, e.g., `sample-iam-federation`. Follow these naming requirements:

          * Length: between 3 and 63 characters.
          * It can only contain lowercase Latin letters, numbers, and hyphens.
          * It must start with a letter and cannot end with a hyphen.
      * `--issuer`: URL of the OIDC provider.

          To get this value, refer to the OIDC provider's documentation or contact their support.
      * `--audiences`: Resources to issue the token for. You can specify multiple resources at once, separated by commas.

          To get this value, refer to the OIDC provider's documentation or contact their support.
      * `--jwks-url`: URL for retrieving the current public key issued by the OIDC provider and used for [JWT](https://en.wikipedia.org/wiki/JSON_Web_Token) signature verification.

          To get this value, refer to the OIDC provider's documentation or contact their support.

      Result:

      ```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"
      ```

      Save the value of the new workload identity federation ID. You will need it to create federated credentials.

      For more information about the `yc iam workload-identity oidc federation create` command, see the [CLI reference](../../../cli/cli-ref/iam/cli-ref/workload-identity/oidc/federation/create.md).

- Terraform {#tf}

  With [Terraform](https://www.terraform.io/), you can quickly create a cloud infrastructure in Yandex Cloud and manage it using configuration files. These files store the infrastructure description written in HashiCorp Configuration Language (HCL). If you change the configuration files, Terraform automatically detects which part of your configuration is already deployed, and what should be added or removed.
  
  Terraform is distributed under the [Business Source License](https://github.com/hashicorp/terraform/blob/main/LICENSE). The [Yandex Cloud provider for Terraform](https://github.com/yandex-cloud/terraform-provider-yandex) is distributed under the [MPL-2.0](https://www.mozilla.org/en-US/MPL/2.0/) license.
  
  For more information about the provider resources, see the relevant documentation on the [Terraform](https://www.terraform.io/docs/providers/yandex/index.html) website or [its mirror](../../../terraform/index.md).

  If you do not have Terraform yet, [install it and configure the Yandex Cloud provider](../../../tutorials/infrastructure-management/terraform-quickstart.md#install-terraform).
  
  
  To manage infrastructure using Terraform under a service account or user accounts (a Yandex account, a federated account, or a local user), [authenticate](../../../terraform/authentication.md) using the appropriate method.

  1. In the Terraform configuration file, define the parameters of the federation you want to create:

      ```hcl
      resource "yandex_iam_workload_identity_oidc_federation" "wlif" {
        name        = "<federation_name>"
        folder_id   = "<folder_ID>"
        audiences   = ["<resource_1>","<resource_2>",...,"<resource_n>"]
        issuer      = "<OIDC_provider_URL>"
        jwks_url    = "<JWKS_address>"
      }
      ```

      Where:

      * `name`: Name of the new federation, e.g., `sample-iam-federation`. Follow these naming requirements:

          * Length: between 3 and 63 characters.
          * It can only contain lowercase Latin letters, numbers, and hyphens.
          * It must start with a letter and cannot end with a hyphen.
      * `folder_id`: [ID](../../../resource-manager/operations/folder/get-id.md) of the folder to create the workload identity federation in.
      * `audiences`: Resources to issue the token for. You can specify multiple resources at once, separated by commas.

          To get this value, refer to the OIDC provider's documentation or contact their support.
      * `issuer`: URL of the OIDC provider.

          To get this value, refer to the OIDC provider's documentation or contact their support.
      * `jwks_url`: URL for retrieving the current public key issued by the OIDC provider and used for [JWT](https://en.wikipedia.org/wiki/JSON_Web_Token) signature verification.

          To get this value, refer to the OIDC provider's documentation or contact their support.

      For more information about `yandex_iam_workload_identity_oidc_federation` properties in Terraform, see [this provider guide](../../../terraform/resources/iam_workload_identity_oidc_federation.md).

  1. Create the resources:

     1. In the terminal, navigate to the configuration file directory.
     1. Make sure the configuration is correct using this command:
     
        ```bash
        terraform validate
        ```
     
        If the configuration is valid, you will get this message:
     
        ```bash
        Success! The configuration is valid.
        ```
     
     1. Run this command:
     
        ```bash
        terraform plan
        ```
     
        You will see a list of resources and their properties. No changes will be made at this step. Terraform will show any errors in the configuration.
     1. Apply the configuration changes:
     
        ```bash
        terraform apply
        ```
     
     1. Type `yes` and press **Enter** to confirm the changes.

     Terraform will create a workload identity federation. You can check the new federation using the [management console](https://console.yandex.cloud) or this CLI command:

     ```bash
     yc iam workload-identity oidc federation list
     ```

- API {#api}

  To create a workload identity federation, use the [create](../../workload/oidc/workload-identity/api-ref/Federation/create.md) REST API method for the [Federation](../../workload/oidc/workload-identity/api-ref/Federation/index.md) resource or the [FederationService/Create](../../workload/oidc/workload-identity/api-ref/grpc/Federation/create.md) gRPC API call.

{% endlist %}

## Create federated credentials {#create-federated-credential}

{% note warning %}

Linking service accounts to workload identity federations may be prohibited by [access policies](../../concepts/access-control/access-policies.md) at the [folder](../../../resource-manager/concepts/resources-hierarchy.md#folder), [cloud](../../../resource-manager/concepts/resources-hierarchy.md#cloud), or [organization](../../../organization/concepts/organization.md) level.

{% endnote %}

Federated credentials refer to the link established between a workload identity federation, a Yandex Cloud service account, and an external subject. Federated credentials are used to identify external subjects in Yandex Identity and Access Management.

{% note info %}

To create federated credentials, the user needs the following:
* `iam.serviceAccounts.federatedCredentialEditor` [role](../../security/index.md#iam-serviceAccounts-federatedCredentialEditor) or higher for the service account that will be used in the federated credentials.
* `iam.workloadIdentityFederations.user` [role](../../security/index.md#iam-workloadIdentityFederations-user) or higher for the folder containing the workload identity federation.

{% endnote %}

{% list tabs group=instructions %}

- Management console {#console}

  1. In the [management console](https://console.yandex.cloud), click ![image](../../../_assets/console-icons/layout-side-content-left.svg) or ![image](../../../_assets/console-icons/chevron-down.svg) in the top panel and select the folder containing the service account.
  
      [Create](../sa/create.md) a new service account if you need to.
  1. In the list of services, select **Identity and Access Management**.
  1. Select the appropriate service account from the list.
  1. In the top panel, click ![image](../../../_assets/console-icons/cpus.svg) **Link to federation**.
  1. In the **Workload identity federation** field, select the federation you created earlier.
  1. In the **Subject value (sub)** field, specify the external subject ID.

      To get this value, refer to the OIDC provider's documentation or contact their support.
  1. Click **Link**.

- CLI {#cli}

  1. View the description of the command for creating federated credentials:

      ```bash
      yc iam workload-identity federated-credential create --help
      ```

  1. Create federated credentials, specifying the ID of the appropriate service account:

      ```bash
      yc iam workload-identity federated-credential create \
        --service-account-id <service_account_ID> \
        --federation-id <federation_ID> \
        --external-subject-id "<external_subject_ID>"
      ```

      Where:

      * `--service-account-id`: [ID](../sa/get-id.md) of the Yandex Cloud service account.

          The service account can reside in a folder other than the one containing the workload identity federation.
      * `--federation-id`: Workload identity federation ID obtained in the previous step.
      * `--external-subject-id`: External subject ID.

          To get this value, refer to the OIDC provider's documentation or contact their support.

      Result:

      ```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"
      ```
            
      For more information about the `yc iam workload-identity federated-credential create` command, see the [CLI reference](../../../cli/cli-ref/iam/cli-ref/workload-identity/federated-credential/create.md).

- Terraform {#tf}

  1. In the Terraform configuration file, define the parameters of the federated credentials you want to create:

      ```hcl
      resource "yandex_iam_workload_identity_federated_credential" "fc" {
        service_account_id  = "<service_account_ID>"
        federation_id       = "<federation_ID>"
        external_subject_id = "<external_subject_ID>"
      }
      ```

      Where:

      * `service_account_id`: [ID](../sa/get-id.md) of the Yandex Cloud service account.

          The service account can reside in a folder other than the one containing the workload identity federation.
      * `federation_id`: Workload identity federation ID.
      * `external_subject_id`: External subject ID.

          To get this value, refer to the OIDC provider's documentation or contact their support.

      For more information about `yandex_iam_workload_identity_federated_credential` properties in Terraform, see [this provider guide](../../../terraform/resources/iam_workload_identity_federated_credential.md).

  1. Create the resources:

     1. In the terminal, navigate to the configuration file directory.
     1. Make sure the configuration is correct using this command:
     
        ```bash
        terraform validate
        ```
     
        If the configuration is valid, you will get this message:
     
        ```bash
        Success! The configuration is valid.
        ```
     
     1. Run this command:
     
        ```bash
        terraform plan
        ```
     
        You will see a list of resources and their properties. No changes will be made at this step. Terraform will show any errors in the configuration.
     1. Apply the configuration changes:
     
        ```bash
        terraform apply
        ```
     
     1. Type `yes` and press **Enter** to confirm the changes.

     Terraform will create the specified federated credentials. You check the new service account federated credentials using the [management console](https://console.yandex.cloud) or this CLI command:

     ```bash
     yc iam workload-identity federated-credential list \
       --service-account-id <service_account_ID>
     ```

- API {#api}

  To create federated credentials, use the [create](../../workload/workload-identity/api-ref/FederatedCredential/create.md) REST API method for the [FederatedCredential](../../workload/workload-identity/api-ref/FederatedCredential/index.md) resource or the [FederatedCredentialService/Create](../../workload/workload-identity/api-ref/grpc/FederatedCredential/create.md) gRPC API call.

{% endlist %}

## Exchange a JWT for a service account IAM token {#exchange-jwt-for-iam}

Send a request to the Yandex Cloud token exchange service:

```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=<service_account_ID>&
     subject_token=<JWT>&
     subject_token_type=urn:ietf:params:oauth:token-type:id_token
```

Where:

* `grant_type`: Request type, which is always `urn:ietf:params:oauth:grant-type:token-exchange`.
* `requested_token_type`: Requested token type, which is always `urn:ietf:params:oauth:token-type:access_token`.
* `audience`: [ID](../sa/get-id.md) of the Yandex Cloud service account.
* `subject_token`: External subject JWT.
* `subject_token_type`: External subject token type, which is always `urn:ietf:params:oauth:token-type:id_token`.

Result:

```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
}
```

Where `access_token` is the requested service account IAM token you can use for authentication when working in the [Yandex Cloud API](../../../api-design-guide/index.md).

## See also {#see-also}

* [Workload identity federations](../../concepts/workload-identity.md).
* [Getting Yandex Lockbox secret value on the GitHub side](../../tutorials/wlif-github-integration.md).
* [Getting Yandex Lockbox secret value on the GitLab side](../../tutorials/wlif-gitlab-integration.md).