Workload identity federations

A workload identity federation is a Yandex Identity and Access Management tool enabling you to configure exchanging tokens of any OpenID Connect-compatible system for IAM tokens that can be used to access the Yandex Cloud API.

Popular use cases:

• Kubernetes pod request to the Yandex Cloud API to get the Yandex Lockbox secret contents.
• Request to the Yandex Cloud API from a CI/CD system, such as GitLab, to deploy cloud services using Terraform.

Such a process does not involve creation of long-lived keys, thus improving both user convenience and security.

For more information about OpenID Connect, see the OIDC specification.

You can use the YC CLI to configure a workload identity federation.

To create a workload identity federation, you need the iam.workloadIdentityFederations.editor role or higher.

How a federation worksHow a federation works

A workload identity federation is created in a folder and requires configuration of required parameters of an OpenID Connect-compatible provider (OIDC provider).

• audience: Resource for which the IAM token will be issued. Provided in StringOrURI format.

  A federation can have a single one or a whole array of the audience values specified.

• issuer: URL of the OIDC provider server.

• jwks-url: URL for retrieving the current public key issued by the OIDC provider and used for JWT signature verification.

You can create multiple workload identity federations in a single folder.

A workload identity federation consists of federated credentials, each containing details about the link between a specific service account and a specific external subject.

An external subject is a subject authorized by a third-party OIDC provider and belonging to a service external to Yandex Cloud and therefore requiring a Yandex Cloud IAM token. For example, this could be a Kubernetes service account or a GitLab job.

Steps to obtain an IAM token using a service account linked to a federation:

1. To get a Yandex Cloud IAM token, an external subject contacts the OIDC provider which issues a JWT token for it.
2. The external subject submits the obtained JWT token to the Yandex Identity and Access Management workload identity federation.
3. Identity and Access Management verifies the external subject's permissions (by checking for the appropriate federated credentials) and the validity of the submitted JWT token (using a public key).
4. Upon successful verification of permissions and the JWT token, Identity and Access Management exchanges the JWT token for an IAM token of the Yandex Cloud service account linked to this external subject through the relevant federated credentials.
5. The external subject uses the obtained IAM token to make the required Yandex Cloud API requests on behalf of the service account specified in the federated credentials.

Federated credentialsFederated credentials

Federated credentials refer to the link established between a workload identity federation, a Yandex Cloud service account, and an external subject.

Federated credentials are created within an identity federation and require configuration of required parameters.

• Service account ID or name: Data of the service account that will get an IAM token upon request from an external subject.

  The service account can reside in a folder other than the one containing the workload identity federation.

  The service account must get roles permitting the required actions with resources or data in Yandex Cloud.

• Workload identity federation ID: Data of the workload identity federation for which federated credentials are being added.

• subject: ID assigned by the OIDC provider to the external subject submitting a request to the Yandex Cloud API.

You can use the YC CLI to create federated credentials.

To create federated credentials, the user needs the following:

• The iam.serviceAccounts.federatedCredentialEditor role or higher for the service account that will be used in the federated credentials.
• The iam.workloadIdentityFederations.user role or higher for the folder containing the relevant workload identity federation.