Yandex Cloud
Search
Contact UsGet started
  • Blog
  • Pricing
  • Documentation
  • All Services
  • System Status
    • Featured
    • Infrastructure & Network
    • Data Platform
    • Containers
    • Developer tools
    • Serverless
    • Security
    • Monitoring & Resources
    • ML & AI
    • Business tools
  • All Solutions
    • By industry
    • By use case
    • Economics and Pricing
    • Security
    • Technical Support
    • Customer Stories
    • Start testing with double trial credits
    • Cloud credits to scale your IT product
    • Gateway to Russia
    • Cloud for Startups
    • Education and Science
    • Yandex Cloud Partner program
  • Blog
  • Pricing
  • Documentation
© 2025 Direct Cursus Technology L.L.C.
Yandex Identity and Access Management
    • Overview
    • Service access to user resources
    • Identity federations
    • Workload identity federations
    • Quotas and limits
  • Secure use of Yandex Cloud
  • Access management
  • Pricing policy
  • Role reference
  • Terraform reference
  • Monitoring metrics
  • Audit Trails events
  • Release notes

In this article:

  • How a federation works
  • Federated credentials
  1. Concepts
  2. Workload identity federations

Workload identity federations

Written by
Yandex Cloud
Updated at May 12, 2025
  • How a federation works
  • Federated credentials

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.

To set up a workload identity federation, use the management console or the Yandex Cloud CLI.

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 JWT to the 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.

You can exchange an external subject's JWT token for a service account's IAM token by sending a POST request to the https://auth.yandex.cloud/oauth/token endpoint.

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 (only when creating federated credentials through the CLI, Terraform, or API).

    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 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.

Was the article helpful?

Previous
Identity federations
Next
Quotas and limits
© 2025 Direct Cursus Technology L.L.C.