Workload Identity Federation lets applications running outside Google Cloudimpersonate a service account by using credentials from an external identity provider.

Using Workload Identity Federation can help you improve security by lettingapplications use the authentication mechanisms that the external environmentprovides and can helpreplace service account keys.

To use Workload Identity Federation securely, you must configure it in a way thatprotects you from the following threats:

• Spoofing: A bad actor might attempt to spoof another user's identity togain unauthorized access to Google Cloud resources.
• Privilege escalation: A bad actor might take advantage ofWorkload Identity Federation to gain access to resources they otherwisewouldn't have access to.
• Non-repudiation: A bad actor might conceal their identity and actionsby using external credentials that make it difficult to trace actions backto them.
• Malicious credential configurations: A bad actor could provide a maliciouscredential configuration to circumvent your security defenses.

This guide presents best practices for deciding when to useWorkload Identity Federation, and how to configure it in a way that helps youminimize risks.

When to use Workload Identity Federation

Use Workload Identity Federation for applications that have access to ambient credentials

Applications running on cloud providers other than Google Cloud oftenhave access to ambient credentials. These are credentials that the applicationcan obtain without having to perform any additional authentication. Examples include:

• On AWS, applications deployed on EC2 can useinstance profiles to assume a role and obtain temporary credentials.
• On Azure, applications can usemanaged identities to obtain access tokens.
• In GitHub Actions, workflows canobtain ID tokens that reflect the deploymentjob's identity.

If the ambient credentials are OpenID Connect (OIDC) tokens, SAML assertions, orAWS credentials, you canconfigure Workload Identity Federationto let applications exchange these credentials for short-lived Google access tokens.If the ambient credentials use a different format, you might be able toexchange them for an OIDC token or SAML assertionfirst, and then use them for Workload Identity Federation.

Use Workload Identity Federation whenever an application needs to accessGoogle Cloud and has access to ambient credentials.

Use an additional token exchange to use ambient credentials that aren't supported by Workload Identity Federation

In some cases, an application might have access to ambient credentials, but thetypes of credentials aren't supported by Workload Identity Federation. In thesecases, check if an additional token exchange lets you convert the ambientcredential into a type of credential that you can use forWorkload Identity Federation.

For example, if your application runs in an Active Directory environment, itmight have access to Kerberos credentials. If you have an identity providersuch as Active Directory Federation Services (AD FS) in your environment thatsupportsIntegrated Windows Authentication,you can use these Kerberos credentials to authenticate to the identity providerand obtain an OAuth access token that uses the JWT format. Using this accesstoken and Workload Identity Federation, you can then let the application performa second token exchange to obtain short-lived Google credentials.

Chaining token exchanges increases complexity and might introduce additionaldependencies, but can free you from having to manage and secure service account keys.

Use Workload Identity Federation to reduce the number of credentials that require rotation

Applications that integrate with an OpenID or SAML identity provider often use aclient secret (or a different form of secret) to authenticate to the identity provider.Typically, this secret is stored as part of the application's configuration.To let such an application access Google Cloud, you must decide between:

1. Creating a service account key and storing it alongside the other secret.
2. Using tokens issued by the existing identity provider and exchanging themfor Google credentials by using Workload Identity Federation.

The first option requires two secrets, but the second option only requires one.Reducing the number of secrets can help you simplifysecret rotation, whichin turn can help improve security.

Using regional Security Token Service endpoints for better reliability

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of theService Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see thelaunch stage descriptions.

Regional Security Token Service endpoints are available for Google Cloud in every region.

Regional Security Token Service endpoints give you control overwhere token exchange occurs, which can enhance performance and reliability,when you follow the guidelines inDesign reliable infrastructure for your workloads.To use regional endpoints, you can usehttps://sts.REGION.rep.googleapis.com.The regions can be retrieved from the discovery doc with the followingcommand. You can then find them in the location field in theEndpoints stanza.

curl'https://sts.googleapis.com/$discovery/rest'

If you use a credential configuration file for authentication, for example, onedownloaded from Google Cloud console, you can do the following:

1. Edit the downloaded file.
2. In thetoken_url field, replacehttps://sts.googleapis.com withhttps://sts.REGION.rep.googleapis.com.

If you use thegcloud iam workload-identity create-cred-config command togenerate the credential configuration file, use the--sts-location=REGIONflag. For example, if you setREGION tous-central1, theGoogle Cloud client will usehttps://sts.us-central1.rep.googleapis.comto acquire related tokens. If--sts-location is unset or set toglobal, thenthe default endpoint domain,https://sts.googleapis.com, is used.

You can use regional endpoint URLs with Private Service Connect. Formore information about endpoint URLs, seeAbout accessing regional endpoints through Private Service Connect endpoints.

Protecting against spoofing threats

A workload identity pool doesn'tcontain any identities or user accounts, whichmakes it different from a user directory such as Cloud Identity. Instead, aworkload identity pool represents aview that surfaces identities from externalidentity providers so that they can be used as IAM principals.

Depending on how you configure the workload identity pool and its providers, thesame external identity might be represented as multiple different IAM principals,or several external identities could map to the same IAM principal. Suchambiguities might allow bad actors to launch spoofing attacks.

The following section describes best practices that help you avoid ambiguous mappings,and reduce the risk of spoofing threats.

Use attribute conditions when federating with GitHub or other multi-tenant identity providers

Workload Identity Federation doesn't maintain a directory of user accounts;instead, it implementsclaims-based identities:As a result, when two tokens are issued by the same identity provider (IdP) and their claims map to the samegoogle.subject value, the two tokens are assumed to identify the same user.To find out which IdP issued a token, Workload Identity Federation inspects andverifies the token's issuer URL.

Some providers, such as GitHub and Terraform Cloud, use a single issuer URL acrossall of their tenants. For these providers, the issuer URL identifiesall of GitHub or Terraform Cloud, not a specific GitHub or Terraform Cloud organization.

When you use these identity providers, it's insufficient to letWorkload Identity Federation check a token's issuer URL to ensure that itcomes from a trusted source and that its claims can be trusted. We recommendthat you configure a Workload Identity Federation attribute condition to checkthat the token originated from a trusted tenant or, in the case of GitHub orTerraform Cloud, a trusted organization.

To learn more, seeconfigure an attribute condition.

Use a dedicated project to manage workload identity pools and providers

Instead of managing workload identity pools and providers across multiple projects,use a single, dedicated project to manage workload identity pools and providers.Using a dedicated project helps you to:

• Ensure that only trusted identity providers are used forWorkload Identity Federation.
• Centrally control access to the configuration of workload identity pools andproviders.
• Apply consistent attribute mappings and conditions across all projects andapplications.

You can use organizational policy constraints to enforce the discipline of usinga dedicated project to manage workload identity pools and providers.

Use organizational policy constraints to disable the creation of workload identity pool providers in other projects

Users with the permission to create workload identity pool providers can createworkload identity pools and providers that might be redundant to the ones youmanage in a dedicated project.

You can prevent the creation of new workload identity pool providers by usingtheconstraints/iam.workloadIdentityPoolProvidersorganizational policy constraint with a rule set toDeny All.

Apply these constraintsat the root of your organizational hierarchy to deny the creation of newworkload identity pool providers by default. Create exceptions for the projectsin which you want to allow the management of workload identity pools andproviders by applying a policy constraint that permits certain, trusted AWSaccounts or OIDC providers.

Use a single provider per workload identity pool to avoid subject collisions

Workload Identity Federation lets you create more than one provider per workloadidentity pool. Using multiple providers can be useful if identities are managedby multiple providers, but you want to hide this complexity from workloadsrunning on Google Cloud.

Using multiple providers introduces a risk of subject collisions, where theattribute mapping forgoogle.subject of one provider returns the same valueas the attribute mapping for another provider. The result of such a collisionis that multiple external identities are mapped to the same IAM principal, makingthe external identities indistinguishable in Cloud Audit Logs.

To avoid subject collisions, use a single provider per workload identity pool.If you need to federate with multiple providers, create multiple workload identitypools, each using a single workload identity provider.

Avoid federating with the same identity provider twice

You can federate with the same identity provider multiple times by creating multipleworkload identity pool providers that use the same or similar configuration.If these providers belong to the same workload identity pool, then such aconfiguration can lead tosubject collisions.If the providers belong to different workload identity pools, subject collisionscan't occur and the same external identity is instead represented as differentIAM principals.

Mapping a single external identity to multiple IAM principals makes it moredifficult to analyze which resources a particular external identity has access to.Such an ambiguity can also increase risk when trying to revoke access: Anadministrator might revoke access for one principal, but might be unaware of theexistence of another principal, inadvertently causing the external identity toretain access.

To minimize the risk of ambiguities, avoid federating with the same identityprovider more than once. Instead, create a single workload identity pool andprovider and use an attribute mapping and condition that ensures that it can beused for all external identities that require access to Google Cloud resources.

Protect the OIDC metadata endpoint of your identity provider

When you federate with an OpenID Connect provider, Workload Identity Federationperiodically downloads the OIDC metadata from your identity provider.Workload Identity Federation uses the IdP's metadata and JSON Web Key Set(JWKS) to validate tokens.

To ensure authenticity, communication with your identity provider is secured byusing TLS. If your provider is deployed behind a load balancer or reverse proxythat terminates TLS, then the TLS connection ensures the authenticity of theload balancer or reverse proxy, but not of the actual identity provider.

A bad actor might be able to take advantage of this setup by launching aman-in-the-middle (MITM) attack in which they reconfigure the load balancer tolet it pass JWKS requests to a malicious endpoint that serves a different setof keys. Swapping the JWKS lets a bad actor sign tokens that are consideredvalid by Workload Identity Federation and might allow them to spoof other user'sidentities.

To protect against JWKS swapping, ensure that your IdP is deployed in a way thatprotects it against MITM attacks.

Use the URL of the workload identity pool provider as the audience

When you federate with an OpenID Connect provider, Workload Identity Federationverifies that the audience of tokens (encoded in theaud claim) matches theallowed audience setting of the provider. Similarly, when you federate with aSAML provider, Workload Identity Federation checks that the SAML assertionspecifies anaudience restriction that matches the expected audience.

By default, Workload Identity Federation expects the audience to match the URLhttps://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_IDthat uniquely identifies the workload identity pool provider. Requiring tokensand assertions to use this URL as the audience helps reduce the risk of aconfused deputy attack. In such an attack, a bad actor presents a token or SAML assertion toWorkload Identity Federation that wasn't intended to be used forWorkload Identity Federation, but for some other API.

Requiring the token or assertion to contain the URL of the target workloadidentity pool provider helps you ensure that clients can only use tokens andassertions that were specifically issued for Workload Identity Federation.

Use immutable attributes in attribute mappings

Togrant an external identity permission to impersonate a service account, you create an IAMbinding that references the external identity by subject, group, or a customattribute. The external identity's subject, group, and custom attributes arederived from the attributes that the external identity provider passes toWorkload Identity Federation during the token exchange.

Some identity providers permit users to change some of their own attributes.For example, a user might be allowed to modify their email address or aliases.If your IAM bindings refer to attributes that are modifiable, then users mightaccidentally lose access to certain resources by modifying their user profile.Or worse, bad actors might be able to gain unauthorized access to other resourcesby deliberately modifying their user attributes to match existing IAM bindings.

To protect against this spoofing threat, limit attribute mappings to attributesthat can't be modified by the user, or can't be modified at all.

Use non-reusable attributes in attribute mappings

When you grant an external identity permission to impersonate a service accountand subsequently delete the user in the external identity provider, then the IAMbinding of the service account remains in place.

If you later add a new user to your external identity provider, and the usershares certain attributes with the previously deleted user (for example, sameemail address), then the old and new users will be indistinguishable forWorkload Identity Federation. As a result, an IAM binding that was meant toonly refer to the old user might apply to the new user too.

To prevent such ambiguities, use attribute mappings that exclusively rely onattributes that can't be reused over time, like a unique user ID.

If your company policy allows the reuse of attributes such as email addresses,then avoid using these attributes in attribute mappings and use a differentattribute instead that's guaranteed to be unique over time.

Don't allow attribute mappings to be modified

Workload Identity Federation usesattribute mappingsto select which of the attributes provided by the external identity providershould be embedded into an STS token, and how the attribute names shouldtranslate. Configuring attribute mappings is a key step to setting up the trustrelationship between the external identity provider and Google Cloud.

Attribute mappings are also crucial to the security of usingWorkload Identity Federation: If you've granted a federated principal orprincipal set the ability toimpersonate a service account,and you then change the attribute mapping, you might change which users haveaccess to the service account.

Modifying attribute mappings requires theiam.googleapis.com/workloadIdentityPoolProviders.update permission. Rolescontaining this permission include:

• Owner (roles/owner)
• IAM Workload Identity Pool Admin(roles/iam.workloadIdentityPoolAdmin)

If a bad actor has permission to modify attribute mappings, they might be ableto change the mapping rules in a way that allows them to spoof their identityand gain access to a service account. To prevent such malicious modifications,make sure only a few administrative users have the permission tomodify attribute mappings.

Consider creating a dedicated Google Cloud project for managing workloadidentity pools, which helps you limit the risk of users inadvertently beinggranted one of these roles at a higher level in the resource hierarchy.

Don't rely on attributes that aren't stable or authoritative

An identity provider uses attributes to communicate information aboutauthenticated users. Identity providers typically guarantee that someattributes are authoritative, but others aren't. For example, an externalidentity provider might embed both a username and a user ID in an OIDC token.Both attributes uniquely identify a user and might seem interchangeable.However, the external identity provider might guarantee that the user ID isstable and authoritative, but allow usernames to be changed.

If your attribute mappings rely on attributes that aren't stable orauthoritative, then a bad actor might be able to spoof their identity bymodifying their user profile in the external identity provider. For example,they might change their username to that of a user that has been recentlydeleted in the external identity provider, but still has access to a serviceaccount on Google Cloud.

To prevent such spoofing attacks, make sure your attribute mappings only rely onattributes that the external identity provider guarantees to be stable andauthoritative.

Protecting against non-repudiation threats

Whenever you notice suspicious activity affecting one of your resources onGoogle Cloud, Cloud Audit Logs are an important source of informationto find out when the activity happened and which users were involved.

When an application uses Workload Identity Federation, it impersonates a serviceaccount. In Cloud Audit Logs, any activity performed by the application isattributed to the impersonated service account. To reconstruct the full chainof events that led to the activity, you must be able to correlate Cloud Audit Logswith the logs of your identity provider so that you can find out which externalidentity was involved, and why an activity was performed.

This section describes best practices that can help you maintain a non-repudiableaudit trail.

Enable data access logs for IAM APIs

To help you identify and understand service account impersonation scenarios,services such as Compute Engine include aserviceAccountDelegationInfo sectionin Cloud Audit Logs. When an application uses Workload Identity Federation, thissectionincludes the subjectof the principal that was used to impersonate the service account.

Not all services include impersonation details in Cloud Audit Logs. To helpmaintain a non-repudiable audit trail, you must also record all impersonationevents byenabling data access logsfor theSecurity Token Service API andIdentity and Access Management API.Enable these logs for all Cloud projects that contain workload identity pools orservice accounts used for Workload Identity Federation.

By enabling these logs, you make sure that an entry is added to the Cloud Audit Logswhenever an application uses Workload Identity Federation toexchange an external credentialandimpersonates a service account.

Use a unique subject mapping

Theprincipal subject used in the serviceAccountDelegationInfo section inCloud Audit Logs entries is determined by your workload identity pool provider'sattribute mapping forgoogle.subject.

When you spot suspicious activity and need to find out which external identitywas involved, you must be able to look up an external identity by its correspondinggoogle.subject value.

Similarly, when an external identity was compromised and you need to find outwhether the identity was used to access Google Cloud resources, you mustbe able to find Cloud Audit Logs entries that correspond to the external identity.

When youdefine the attribute mappingfor a workload identity pool provider, choose a unique mapping forgoogle.subject so that:

• An external identity maps to exactly onegoogle.subject value.
• Agoogle.subject value maps to exactly one external identity.
• You can look up an external identity by itsgoogle.subject value.

Using an attribute mapping that satisfies these uniqueness criteria helps youensure that you can look up external identities by theirgoogle.subject value,andgoogle.subject values by their external identities.

Protecting against privilege escalation threats

To apply the principle of least privilege when using Workload Identity Federation,you must:

• limit the number of external identities that can impersonate a service account
• limit the resources that a service account can access

An overly permissive configuration can lead to a situation where a bad actor canuse an external identity to escalate their privileges and access resources theyshouldn't have access to.

The following sections provide best practices that can help you protect againstprivilege escalation threats.

Use service accounts that reside in the same project as the resources you need to access

When a client uses Workload Identity Federationby using client libraries orthe REST API,it follows a three-step process:

1. Obtain a credential from the trusted identity provider.
2. Exchange the credential for a token from the Security Token Service.
3. Use the token from the Security Token Service to impersonate a serviceaccount and obtain a short-lived Google access token.

For the last step, use a service account that resides in the same project as theresources you need to access. Using a service account that's managed in the sameproject helps you apply more restrictive access permissions, and makes it easierto decide when the service account might not be needed anymore.

Use a dedicated service account for each application

If you have multiple applications that use Workload Identity Federation to accessresources in the same project, create a dedicated service account for eachapplication. Using application-specific service accounts helps you avoidover-permissioning by only granting access to resources that each individualapplication requires.

Avoid granting access to all members of a pool

Before an external identity can impersonate a service account, you mustgrant it theroles/iam.workloadIdentityUser role on the service account. When you grant thisrole, avoid granting it to all members of the workload identity pool. Instead,grant the role to specific external identities, or to identities that matchcertain criteria.

Initially, the number of external users that need access to Google Cloudresources might be small. The attribute condition of your workload identity pooland the configuration of your identity provider might therefore only permit a fewexternal identities to use Workload Identity Federation.

When you later onboard new workloads to Google Cloud, you might need tomodify your identity provider's configuration or the workload identity pool'sattribute condition so that it allows additional external identities.

By only granting theroles/iam.workloadIdentityUser role to specific externalidentities, you can ensure that you can safely grow a workload identity poolwithout inadvertently granting more external identities impersonation access thannecessary.

Protecting against malicious credential configurations

Some credential configurations contain URLs and file paths that, if notappropriately validated by a workload, could cause the workload to use maliciousendpoints.

Validate credential configurations from an external source before using them to authenticate to Google APIs

When you accept a credential configuration from an external source, you mustvalidate the JSON before using it. If you don't validate the credentialconfiguration, a malicious actor could use the credential configuration to causeyour workload to access malicious endpoints.

For more information, seeSecurity requirements when using credential configurations from an external source.

What's next

• Learn aboutbest practices for working with service accounts.
• Read more aboutbest practices for managing service account keys.