Workload identity federations
Note
This feature is in the Preview stage. To get access, contact tech support
A workload identity federation is a Yandex Identity and Access Management tool that enables you to configure exchange of tokens from any OpenID Connect
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 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 inStringOrURI
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:
- To get a Yandex Cloud IAM token, an external subject contacts the OIDC provider which issues a JWT token for it.
- The external subject submits the obtained JWT token to the Yandex Identity and Access Management workload identity federation.
- 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).
- 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.
- 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 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: