Configuring Workload Identity Federation for External Workloads

Attribute mapping and policy configuration in Workload Identity Federation (opens in a new tab) turn claims from an external identity provider into Google Cloud identities that Identity and Access Management (IAM) can authorize. An attribute mapping on a workload identity pool provider translates fields from the external token, referenced as assertion, into Google attributes such as google.subject, google.groups, and custom attributes. IAM allow policies then grant roles to principal identifiers built from those mapped values, so only matching external workloads receive access without using service account keys.

1.1Attribute Mappings That Define Federated Identity

Attribute mappings on a workload identity pool provider select which external token attributes are embedded into the Security Token Service (STS) token and how their names translate to Google attributes. The mapping for google.subject defines the federated subject, for example google.subject=assertion.sub maps the external sub claim to the Google subject. A mapping for google.groups exposes group membership, while custom mappings create additional attributes such as attribute.ATTRIBUTE_NAME for fine-grained selection.

Secure mappings rely only on attributes that are stable, authoritative, and unique over time. An external provider may guarantee that a user ID is stable while allowing a username or email address to change or be reused after deletion, so mapping a reusable value can let a new user inherit an old binding. A strong google.subject mapping is one-to-one in both directions: one external identity maps to exactly one subject value, one subject value maps back to exactly one external identity, and either side can be looked up from audit logs. Changing a mapping after access is granted can change which external users match an existing IAM binding, so mappings must be treated as a security boundary.

1.2Principal Identifiers That Encode Mapped Attributes

Principal identifiers in IAM policies reference federated identities by their mapped attribute values inside a specific workload identity pool. All identifiers use the project number of the project that contains the pool, the pool ID, and the expected mapped value, and they apply to any Google Cloud resource that supports IAM allow policies.

The following table compares the three selector types by their IAM member format and when to use each selector.

In these formats, SUBJECT is the expected value of the attribute mapped to google.subject, GROUP is the expected value mapped to google.groups, and ATTRIBUTE_NAME and ATTRIBUTE_VALUE are the name and value from a custom attribute mapping. A single-subject grant uses principal://, while group and custom-attribute grants address a set of matching identities with principalSet://.

1.3Policy Paths for Direct Resource Access and Impersonation

IAM policies for federated workloads follow two paths: direct resource access and service account impersonation. With direct access, the federated principal identifier is granted a resource role directly, such as roles/storage.objectViewer on a Cloud Storage bucket through gcloud storage buckets add-iam-policy-binding. With impersonation, a dedicated Google Cloud service account is granted access to resources, and the federated identifier is then granted roles/iam.workloadIdentityUser on that service account through gcloud iam service-accounts add-iam-policy-binding.

The impersonation flow depends on the service account, the pool, and the STS exchange in order:

1. Obtain external credential: The workload obtains a credential from the trusted external provider.
2. Exchange for STS token: The credential is exchanged with STS for a short-lived federated token that carries the mapped attributes.
3. Impersonate service account: The federated token is used to impersonate the service account and obtain a short-lived Google access token for API calls.

In the console, impersonation is configured from Workload Identity Pools by selecting Grant access, choosing Grant access using Service Account impersonation, selecting the service account, and then choosing Only identities matching the filter with an Attribute name and Attribute value. For example, when the mapping is google.subject=assertion.sub, the filter uses Attribute name subject and the expected sub claim value. Best practice is to use a dedicated service account for each workload, keep that service account in the same project as the resources it accesses, and avoid granting roles/iam.workloadIdentityUser to all members of a pool.

1.4Controls That Protect Mappings From Spoofing and Escalation

Controls around mappings protect against spoofing, unintended access changes, and loss of auditability. Modifying a provider mapping requires the iam.googleapis.com/workloadIdentityPoolProviders.update permission, which is included in Owner (roles/owner) and IAM Workload Identity Pool Admin (roles/iam.workloadIdentityPoolAdmin). Limiting that permission to a few administrators and considering a dedicated project for workload identity pools reduces the risk that someone changes mapping rules to impersonate an authorized identity or that broad roles inherited higher in the hierarchy grant unintended update rights.

Auditability depends on preserving the link between the external identity and the impersonated service account. Services such as Compute Engine may include a serviceAccountDelegationInfo section with the federated subject in Cloud Audit Logs, but not all services do. To maintain a complete trail, enable data access logs for the Security Token Service API and the Identity and Access Management API in every project that contains workload identity pools or service accounts used for federation, so both the credential exchange and the creation of short-lived service account credentials are recorded.

Managing and securing the federation lifecycle means controlling how external identities exchange credentials for Google Cloud access, how those short-lived sessions are monitored, and how configurations are audited, rotated, and removed. Workload Identity Federation lets workloads from Amazon Web Services (AWS), Microsoft Azure, or any OpenID Connect (OIDC) provider impersonate a service account without service account keys, while Workforce Identity Federation (opens in a new tab) extends the same token-exchange model to human users from providers such as Microsoft Entra ID or PingFederate. In both cases, the lifecycle centers on the Security Token Service (STS) at https://sts.googleapis.com/v1/token and the Cloud OAuth API at cloudoauth.googleapis.com for workforce OAuth flows.

2.1Credential Exchange Through the Security Token Service

The Security Token Service exchange is the process where an identity provider (IdP)-issued subject token is posted to Google Cloud and returned as a short-lived Google Cloud access token. The client sends an HTTP POST to https://sts.googleapis.com/v1/token with grant_type=urn:ietf:params:oauth:grant-type:token-exchange, requested_token_type=urn:ietf:params:oauth:token-type:access_token, an audience that names the specific pool and provider, a subject_token_type, the subject_token itself, and a scope such as https://www.googleapis.com/auth/cloud-platform. The audience binds the request to one federation trust, for example //iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID, and the subject_token_type must match the incoming format, either urn:ietf:params:oauth:token-type:id_token for OIDC JWTs or urn:ietf:params:oauth:token-type:saml2 for SAML assertions. A billing and quota project is supplied through options={"userProject":"BILLING_PROJECT_NUMBER"}, and the principal must have the serviceusage.services.use permission on that project or the exchange fails.

A successful exchange returns a Bearer access token that flows from STS to the workload or user session for use against Google Cloud APIs. The response contains access_token, issued_token_type, token_type: Bearer, and expires_in, commonly 3600 seconds, and for Distributed Cloud cluster authentication the default OAuth 2.0 access token lifetime is 1 hour. Credential configuration files generated by gcloud iam workload-identity-pools create-cred-config hold only non-sensitive metadata that tells libraries how to retrieve the external subject token and where to exchange it, including type: external_account, audience, subject_token_type, token_url, and credential_source. Because the file does not contain a long-lived secret, compromise of the file alone does not grant persistent access without a valid, current IdP token.

2.2Session Monitoring and Refresh With gcloud CLI and OAuth APIs

Session monitoring for federation tracks which temporary credentials are active, when they expire, and whether the underlying IdP identity is still valid. The gcloud CLI transparently posts credentials from the file supplied by gcloud auth login --cred-file=config.json to STS and then uses the returned temporary Google Cloud access token for subsequent calls. When that token is about to expire, gcloud CLI inspects the credential configuration file and the validity of the IdP-issued credentials; if the IdP credentials are still valid, gcloud CLI obtains a new Google Cloud access token without interruption, and if they have expired, no new token is issued and calls fail until the user re-authenticates.

Operators monitor and control these sessions with explicit gcloud CLI lifecycle commands. The command gcloud auth list shows credentialed sessions and the active account, gcloud config set account principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/SUBJECT_ID switches the active federated session, and gcloud auth revoke terminates the session. Access can be verified by listing resources the federated principal is authorized for, such as gcloud storage ls --project="TEST_PROJECT_ID" or gcloud alpha storage ls, which also confirms the serviceusage.services.use permission on the session project. For workforce OAuth integrations, the Cloud OAuth API exchanges a Google Cloud authorization code for an access token plus refresh token at https://cloudoauth.googleapis.com/v1/organizations/ORGANIZATION_ID/token, and later uses grant_type=refresh_token to obtain a new short-lived access token when the old one expires.

2.3Security Controls That Limit Token Misuse

Security controls for federation limit what a stolen or replayed token can do by binding it to a narrow audience, a short lifetime, and explicit impersonation rights. Audience binding ensures a subject token issued for one pool and provider cannot be exchanged at a different audience resource name, and the required subject_token_type prevents an OIDC token from being accepted where a SAML assertion is expected. Short lifetimes of 3600 seconds or 1 hour shrink the window in which a Bearer token is useful, and automatic refresh never extends access beyond the validity of the IdP session itself. For workforce calls, the Cloud OAuth API accepts only one client authentication method per request, either HTTP Basic authentication with Base64-encoded CLIENT_ID:CLIENT_SECRET in the Authorization header or client_id and client_secret in the request body, and combining methods returns an error while JWT bearer client assertions are not supported.

Additional controls govern how credentials are sourced and how impersonation is allowed. Executable-sourced credentials require the environment variable GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES to be set to 1, and the local executable must write a valid, unexpired OIDC ID token or SAML assertion in JSON format to stdout, which prevents arbitrary executables from silently supplying tokens. ImpersonatedCredentials let a federated principal act as a target service account without holding its private key, but the principal's project must have the IAMCredentials API enabled and the principal must hold the Service Account Token Creator role on the target service account. X.509 certificate-sourced configurations separate the credential file from private key material through credential-cert-path, credential-cert-private-key-path, and credential-cert-trust-chain-path, with either default discovery at certificate_config.json or an explicit certificate_config_location for custom paths.

2.4Auditing, Rotation, and Decommissioning Federation Trusts

Auditing and rotation for federation verify who can federate, what they can impersonate, and whether stale trusts or keys remain. Application Default Credentials (ADC) resolution follows a fixed search order that auditors must account for:

1. Environment variable file: Credentials file pointed to by GOOGLE_APPLICATION_CREDENTIALS.
2. gcloud ADC login: Credentials from gcloud auth application-default login.
3. App Engine: Google App Engine built-in credentials.
4. Cloud Shell: Google Cloud Shell built-in credentials.
5. Compute Engine: Google Compute Engine built-in credentials, skippable with NO_GCE_CHECK=true and customizable with GCE_METADATA_HOST.

Service account permissions require special audit attention because some permissions enable broader token operations than their names suggest. The permission iam.serviceAccounts.getAccessToken enables getting an access token, iam.serviceAccounts.getOpenIdToken enables getting an ID token, while iam.serviceAccounts.signJwt and iam.serviceAccounts.signBlob both enable signing data and obtaining access or ID tokens through JWT bearer flows. Best practice is to audit service accounts, keys, and allow policies through the IAM API, disable or delete service account keys when federation can be used instead, remove unneeded users from allow policies, grant the fewest permissions possible, and treat default service accounts with caution because they carry the Editor role.

Rotation and deletion complete the lifecycle by replacing configuration without outage and ensuring removed identities lose access. Rotation means regenerating credential configuration files with gcloud iam workload-identity-pools create-cred-config when pool IDs, provider IDs, service account emails, certificate paths, or trust chains change, and rotating any remaining service account key material promptly because longer-lived key material is considered less secure. Deleting a user in the external IdP does not automatically delete Google Cloud side metadata, so administrators must explicitly delete Workforce Identity Federation users and their data as a long-running operation. After deletion is initiated, processes the user started before deletion can continue until they complete or are canceled, and resources may appear associated with the deleted user until that operation finishes.

2.5Choosing Direct Access Versus Service Account Impersonation

Federated workloads can reach Google Cloud resources through two access patterns that differ in identity, management, and blast radius. Direct Workload Identity Federation access grants IAM roles to the federated principal itself, while impersonation grants the federated principal permission to act as a Google service account that already holds resource permissions.

The following table compares the identity used on resources and when to choose each access pattern.

Direct access reduces service account sprawl because each workload keeps its own federated identity, while impersonation centralizes permission management on the target service account at the cost of requiring Token Creator grants and the IAMCredentials API. Both patterns avoid downloading, storing, and rotating service account private keys, which lowers maintenance burden and removes a long-lived secret that could be exfiltrated and reused outside the federation trust boundary.

Architecting a federation trust relationship means configuring Google Cloud to accept identities issued by an external identity provider (IdP) so external workloads can access Google Cloud resources without long-lived secrets. Workload Identity Federation (opens in a new tab) is the trust broker in this design: the external IdP authenticates the workload, Google Cloud validates that external credential, and the workload receives short-lived credentials to temporarily impersonate a service account. The service account then becomes the Google Cloud identity used for authorization.

3.1External Identity Provider Capabilities

External identity provider capabilities determine which workloads can federate and which protocol Google Cloud will use to validate them. Workload Identity Federation supports OpenID Connect (OIDC)-compatible IdPs and SAML 2.0-compatible IdPs, which covers most enterprise and multi-cloud sources without requiring service account keys.

Common external sources documented for federation include:

• Active Directory Domain Services (AD DS) and Active Directory Lightweight Directory Services (AD LDS)
• Microsoft Entra ID, formerly Azure Active Directory
• Identity-as-a-service providers such as ForgeRock, Okta, or Ping Identity
• Other LDAP directories
• Cloud and DevOps platforms such as AWS, Azure, GitHub, and GitLab

An IdP in this model both authenticates the workload and decides whether authentication succeeds, while lifecycle management of the underlying identity may live in a separate human resources or directory system. Architecting trust therefore starts by confirming that the external system can issue OIDC or SAML 2.0 credentials that Google Cloud can validate, and by inventorying whether one pool or multiple forests, tenants, or directories must be integrated.

3.2Establishing Trust Between an External IdP and Google Cloud

Establishing trust for external workloads means configuring Workload Identity Federation as the preferred identity path instead of distributing service account keys. The workload never authenticates directly to Google Cloud APIs with a long-lived key; traffic flows from the external IdP to Google Cloud token exchange, then from Google Cloud to the target API under a service account identity.

The trust flow operates in order:

1. External authentication: The workload authenticates to its external IdP, such as AWS, Azure, Active Directory, or GitHub, and obtains that provider's native credential.
2. Short-lived credential exchange: Google Cloud validates the external credential through Workload Identity Federation and generates short-lived credentials, most commonly OAuth 2.0 access tokens and OpenID Connect (OIDC) ID tokens.
3. Service account impersonation: The workload uses the short-lived credential to temporarily impersonate a designated Google Cloud service account.
4. Resource access: The workload accesses Google Cloud resources using the service account as its identity, subject to the Identity and Access Management (IAM) roles granted to that service account.

For applications running outside Google Cloud, the application uses a credential configuration file to bind this flow together. The file tells client libraries where to obtain the external credential and which service account to impersonate, so no private RSA key material is stored with the application.

3.3Conditions for Impersonating Service Accounts

The condition for impersonation is that access is granted to the service account, not directly to the external workload, and the workload is then permitted to act as that service account. Instead of granting IAM roles to an AWS role, Azure identity, or GitHub identity directly, the architect grants roles to the Google Cloud service account and configures federation to allow specific external identities to impersonate it. The external identity proves who it is to its own IdP, and Google Cloud enforces whether that proven identity is allowed to mint short-lived tokens for the service account.

This separation preserves least privilege and removes key management. Attached service accounts provide a default identity for workloads running on Google Cloud resources, while external workloads achieve the same outcome through federation plus impersonation. When the short-lived token expires, the workload must re-authenticate to its external IdP and repeat the exchange, so compromise of a token has limited lifetime compared to compromise of a service account key.

3.4Trust Models for Google Kubernetes Engine Workloads

Workload Identity Federation for GKE supports two distinct trust models for Kubernetes service accounts accessing Google Cloud services. In the direct resource access model, IAM roles are granted directly to the Kubernetes service account identity on the Google Cloud resource, so the pod identity is evaluated without an intermediate Google service account. In the impersonation model, the Kubernetes ServiceAccount is bound to an IAM service account, and that service account serves as the identity when calling Google Cloud APIs.

The following table compares the identity evaluated by Google Cloud and when to choose each model.

Most Google Cloud APIs support direct resource access, but certain API methods have limitations under identity federation. GKE allows distinct, fine-grained sets of principals for each application in the cluster, so different namespaces or service accounts can use different models while sharing one cluster control plane.

Key Facts

• Workload Identity Federation maps external token claims via assertion to google.subject, google.groups, and custom attributes, and IAM grants use principal:// for a single subject and principalSet:// for groups or custom attributes with the numeric project number.
• Federated workloads gain access either by direct IAM role grants on the federated principal or by impersonating a dedicated service account with roles/iam.workloadIdentityUser.
• The Security Token Service at https://sts.googleapis.com/v1/token exchanges an IdP subject token bound to a specific pool and provider audience for a short-lived Bearer token commonly lasting 3600 seconds.
• Changing a workload identity pool provider attribute mapping can change which external identities match existing IAM bindings and requires iam.googleapis.com/workloadIdentityPoolProviders.update.
• Application Default Credentials resolve in fixed order from GOOGLE_APPLICATION_CREDENTIALS to gcloud ADC login, App Engine, Cloud Shell, and Compute Engine credentials.