This document provides an overview of Workload Identity Federation.Using Workload Identity Federation, you can provide on-premises or multicloudworkloads with access to Google Cloud resources by using federated identitiesinstead of a service account key.

You can use Workload Identity Federation with workloads that authenticateusingX.509 client certificates;that run onAmazon Web Services (AWS) or Azure;on-premisesActive Directory;deployment services, such asGitHub and GitLab;and with any identity provider (IdP) that supportsOpenID Connect (OIDC) or Security Assertion Markup Language (SAML) V2.0).

Why Workload Identity Federation?

Applications running outside Google Cloud can useservice account keysto access Google Cloud resources. However, service account keys arepowerful credentials, and can present a security risk if they are not managedcorrectly. Workload Identity Federation eliminates the maintenance andsecurity burden associated with service account keys.

With Workload Identity Federation, you can use Identity and Access Management (IAM)to grantIAM roles toprincipalsthat are based on federated identities in a workload identity pool. You cangrant access to the principals on specific Google Cloud resources. Thisapproach is calleddirect access. Alternatively, you can grant access to aservice account, which can then access Google Cloud resources. Thisapproach is calledservice account impersonation.

Workload identity pools

Aworkload identity pool is an entity that lets you manage externalidentities.

In general, we recommend creating a new pool for each non-Google Cloudenvironment that needs to access Google Cloud resources, such asdevelopment, staging, or production environments.

Workload identity pool providers

Aworkload identity pool provider is an entity that describes a relationshipbetween Google Cloud and your IdP, including the following:

• AWS
• Microsoft Entra ID
• GitHub
• GitLab
• Kubernetes clusters
• Okta
• On-premises Active Directory Federation Services (AD FS)
• Terraform

Workload Identity Federation follows theOAuth 2.0 token exchangespecification. You provide a credential from your IdP to theSecurity Token Service,which verifies the identity on the credential, and then returns a federatedtoken in exchange.

OIDC provider with local JWKs

To federate workloads that don't have a public OIDC endpoint, you can uploadOIDC JSON Web Key Sets (JWKS) directly to the pool. This is common if you haveTerraform or GitHub Enterprise hosted in your own environment or you haveregulatory requirements not to expose public URLs. For more information, seeManage OIDC JWKs (Optional).

Attribute mappings

The tokens issued by your external IdP contain one or moreattributes. Some IdPs refer to these attributes asclaims.

Google Security Token Service tokens also contain one or more attributes, as listedin the following table:

An attribute mapping defines how to derive the value of the GoogleSecurity Token Service token attribute from an external token. For each GoogleSecurity Token Service token attribute, you can define an attribute mapping,formatted as follows:

TARGET_ATTRIBUTE=SOURCE_EXPRESSION

Replace the following:

• TARGET_ATTRIBUTE is an attribute of the GoogleSecurity Token Service token
• SOURCE_EXPRESSION is aCommon Expression Language (CEL)expression that transforms one or more attributes from the tokens issued byyour external IdP

The following list provides attribute mapping examples:

• Assign the assertion attributesub togoogle.subject:

  google.subject=assertion.sub

• Concatenate multiple assertion attributes:

  google.subject='myprovider::' + assertion.aud + '::' + assertion.sub

• Map a GUID-valued assertion attributeworkload_idto a name, and assign the result to a custom attribute namedattribute.my_display_name:

  attribute.my_display_name={  "8bb39bdb-1cc5-4447-b7db-a19e920eb111": "Workload1",  "55d36609-9bcf-48e0-a366-a3cf19027d2a": "Workload2"}[assertion.workload_id]

• Use CELlogical operators and functionsto set a custom attribute namedattribute.environment to eitherprod ortest, depending on the identity's Amazon Resource Name (ARN):

  attribute.environment=assertion.arn.contains(":instance-profile/Production") ? "prod" : "test"

• Use theextract functionto populate a custom attributeaws_role with the name of the assumed role or,if no role has been assumed, with the identity's ARN.

  attribute.aws_role=assertion.arn.contains('assumed-role') ? assertion.arn.extract('{account_arn}assumed-role/') + 'assumed-role/' + assertion.arn.extract('assumed-role/{role_name}/') : assertion.arn

• Use thesplit functionsplits a string on the provided separator value. For example, to extract the attributeusername from an email address attribute by splitting its value at the@ and using the first string, use the following attribute mapping:

  attribute.username=assertion.email.split("@")[0]

• join functionjoins a list of strings on the provided separator value. For example, to populates the custom attributedepartment by concatenating a list of stringswith. as a separator, use the following attribute mapping:

  attribute.department=assertion.department.join(".")

When you use X.509 client certificates, Google provides default mappings fromcertificate attributes.

For AWS, Google provides default mappings, which cover most common scenarios.You can also supply custom mappings.

For OIDC providers, you supply the mappings. To construct the mapping, consultthe provider's documentation for a list of attributes on their credentials.

For more details, see the API documentation for theattributeMapping field.

Attribute conditions

Anattribute condition is a CEL expression that can check assertion attributesand target attributes. If the attribute condition evaluates totrue for agiven credential, the credential is accepted. Otherwise, the credential isrejected.

You can use an attribute condition to restrict which identities can authenticateusing your workload identity pool.

Attribute conditions are useful in scenarios such as the following:

• If your workload uses an IdP that's available to the generalpublic, you can restrict access so only the identities you choose have accessto your workload identity pool.

• If you're using an IdP with multiple cloud platforms, you canprevent credentials intended for use with another platform from being usedwith Google Cloud, and vice-versa. This helps avoid theconfused deputy problem.

The attribute condition for a workload identity pool provider can use theassertion keyword, which refers to a map that represents the authenticationcredential issued by the IdP. You can use dot notation to accessthe map's values. For example, AWS credentials include anarn value, which youcan access asassertion.arn. In addition, the attribute condition can use anyattribute that is defined in the provider'sattribute mapping.

The following example only allows requests from identities that have a specificAWS role:

attribute.aws_role=="ROLE_MAPPING"

For more details, see the API documentation for theattributeCondition field.

Access management

The token exchange flow returns a federated access token. You can use thisfederated access token to grant your workload access on behalf ofprincipal identities on Google Cloud resources and obtain ashort-lived OAuth 2.0 access token.

You can use this access token to provide IAM access.

We recommend that you use Workload Identity Federation to provide accessdirectly to a Google Cloud resource.Although most Google Cloud APIs support Workload Identity Federation,some APIs havelimitations.As an alternative, you can useservice account impersonation.

The short-lived access token lets you call any Google Cloud APIs that theresource or service account has access to.

Direct resource access

You can usedirect resource access to grant to your external identity accessdirectly on a Google Cloud resource using resource-specific roles.

Alternative: Service account impersonation

As an alternative to providingdirect resource access youcan useservice account impersonation.

You grant access to principals or subsets thereof by usingprincipal types.

Principal types

The following table describes how to define principals as individuals and groupsof identities:

What's next

• Use Workload Identity Federation to let your workloads access resourcesfromAWS or Azure,X.509 Certificates,Active Directory,Deployment pipelines, orOIDC or SAML providers.

• Learn how tomanage workload identity poolsusing the Google Cloud CLI or the REST API.