Configuring Workload Identity Federation.

Architect Federation Trust Relationships

Workload Identity Federation creates a secure trust relationship between Google Cloud and external identity providers such as AWS, Azure, Active Directory, or any OIDC and SAML identity system. This architecture removes the need to manage long-lived service account keys, which are a common security risk. The setup requires a workload identity pool to group external identities and a workload identity pool provider to define the cryptographic trust with the external system. When an external workload needs access, it presents a token to Google Cloud’s Security Token Service (STS), which validates the token using the provider’s metadata and then issues short-lived Google Cloud credentials.

During the token exchange, administrators control access through attribute mapping and attribute conditions. Attribute mapping translates claims from the external token (like a user ID or group membership) into Google Cloud standard attributes such as google.subject. Attribute conditions use Common Expression Language (CEL) to restrict authentication based on specific token values—for example, allowing only tokens from a certain tenant. After validation, the STS returns a federated access token that the workload can use to impersonate a Google Cloud service account. To enable this, the external identity must be granted the Workload Identity User role (roles/iam.workloadIdentityUser) on the target service account. The workload then calls the IAM Service Account Credentials API to assume that identity, applying the principle of least privilege.

Architecting a dependable federation also requires planning for availability. If the external identity provider goes down, workloads cannot complete the token exchange and lose access to Google Cloud resources. Organizations must ensure that the external authentication endpoints and network links are highly available, matching the business continuity requirements. Deploying redundant IdP infrastructure or replicating directory services prevents third-party outages from disrupting cloud operations.

Implement Attribute Mapping and Policy Configuration

Attribute mapping is the mechanism that translates claims from an external identity token (such as an OIDC ID token or SAML assertion) into Google Cloud-specific attributes like google.subject or google.groups. These mapped attributes are embedded into the short-lived STS token, allowing Google Cloud to recognize and trust the external identity. The mapping is defined when configuring the workload identity pool provider and determines which external identities are recognized and what their Google Cloud principal identifiers will be.

Once attributes are mapped, you can build precise IAM policies that grant access based on these attributes. Instead of granting roles to an entire pool, you bind roles to specific principal sets filtered by attribute values. For example, you can grant the roles/storage.objectViewer role to principalSet://.../attribute.team/analysts. You can also use mapped attributes inside IAM Conditions to create conditional rules—for instance, allowing access only if the token’s google.groups claim contains a specific value. This enforces least privilege by limiting access to only the workloads that match the expected attributes.

A common use case is controlling service account impersonation through attribute mappings. You grant the roles/iam.workloadIdentityUser role on a service account, but the IAM binding’s member field uses a principal set filtered by an attribute like subject. This means only external tokens whose mapped google.subject matches a specific value can impersonate that service account. This allows external workloads to act as a dedicated service account without distributing static keys. When designing attribute mappings, use stable, unique, and authoritative claims from the external provider (such as a user ID) rather than mutable ones (like an email) to prevent identity spoofing. Also, restrict the iam.workloadIdentityPoolProviders.update permission to prevent unauthorized changes to the mappings.

Manage and Secure the Federation Lifecycle

Workload Identity Federation eliminates the need to create and manage long-lived service account keys by using short-lived Google Cloud credentials obtained through a secure token exchange. Workloads authenticate with external identity providers like AWS or Microsoft Entra ID and receive temporary credentials from the Security Token Service (STS). This approach removes the security risks of storing and rotating keys. The federation setup begins with a workload identity pool that establishes trust between the external provider and Google Cloud.

To configure federation, prepare the external identity provider. For AWS, no changes are needed in the AWS account—after trust is established, AWS roles can use their existing credentials to get short-lived Google Cloud tokens. For Microsoft Entra ID, administrators create an application registration and note the Application ID URI for the workload identity pool provider. Azure managed identities can also be used to obtain tokens without embedding credentials in code. The credential exchange process involves generating a credential configuration file that specifies the provider details, subject token type, and audience. The gcloud CLI can use this file to transparently handle the token exchange when accessing Google Cloud resources.

Security controls include validating credential configuration files from external sources to ensure the type field matches the expected credential type and using type-specific loaders that parse only valid fields. This prevents malicious actors from exploiting configuration files to gain unauthorized access. For service account impersonation, grant the Service Account Token Creator role (roles/iam.serviceAccountTokenCreator) to the external identity, which includes the iam.serviceAccounts.getAccessToken permission. Use least-privilege access by granting specific roles rather than broad Owner, Editor, or Viewer roles to the service accounts used in federation.

Organizations must also establish procedures for auditing federation configurations and rotating credentials. Unlike user access tokens, service account access tokens cannot be revoked through the Admin Console. If a service account is compromised, disable it, delete any existing keys, and wait 60 minutes for short-lived tokens to expire before re-enabling. Alternatively, delete and replace the service account immediately, which revokes all credentials but may require updating application configurations. Regularly review IAM policies, monitor access patterns through Cloud Logging, and rotate federation configurations to maintain a strong security posture. Always validate that credential configurations from external sources are trusted before use.