Configuring Workforce Identity Federation

Configure Workforce Pools and External Identity Providers

Workforce Identity Federation enables external users, such as employees, contractors, and partners, to access Google Cloud resources using their existing corporate credentials. Instead of synchronizing or creating individual Google accounts, Google Cloud establishes a trust relationship directly with an external identity provider (IdP) like Okta or Microsoft Active Directory. Authentication decisions happen entirely within the external IdP, allowing users to sign in seamlessly via single sign-on (SSO). This model enforces the principle of least privilege by evaluating identity assertions dynamically at login time rather than managing static credentials.

Establishing Federation and Trust

Administrators begin by creating a workforce identity pool at the organization level, which serves as the administrative boundary for managing external identities. Inside this pool, administrators configure one or more workforce identity pool providers using standard industry protocols:

• SAML 2.0 requires exchanging XML metadata documents containing identity provider signing certificates and service endpoints.
• OpenID Connect (OIDC) requires exchanging the client ID, client secret, and relevant authorization or token endpoints.

While workforce identity federation manages human access, machine-to-machine communication for applications hosted outside Google Cloud relies on workload identity federation.

Define Attribute Mappings and Assertion Conditions

Attribute Mapping and Transformations

Once trust is established, attribute mapping translates incoming claims from the external IdP into Google Cloud principal attributes. Mapping the google.subject attribute is required because it defines the unique principal identifier written to Cloud Audit Logs. Administrators should always map google.subject to immutable, non-reusable claims rather than mutable values like email addresses to prevent account spoofing. Optional target attributes include google.groups for group-based access and google.display_name for user identification in the Google Cloud console.

Administrators use Common Expression Language (CEL) to transform and filter claims up to a total mapping limit of 16 KB. Because SAML assertions supply attributes as lists by default, any target expecting a single value must extract an element by index, whereas google.groups accepts a list of strings. Common CEL operations include:

• Concatenating multiple claim values using the join function
• Extracting specific prefixes or substrings using the split function
• Merging incoming group lists conditionally using ternary logic expressions

If an incoming assertion contains more than 400 groups, the sign-in request fails automatically unless group filtering expressions are applied.

Assertion Conditions and Security Boundaries

An attribute condition is an optional boolean CEL expression evaluated before Google Cloud issues short-lived session credentials. This condition acts as an authorization gate, checking incoming assertions against criteria such as corporate group membership, IP address ranges, or multifactor authentication status. Evaluating conditions is critical when integrating with multi-tenant IdPs that share a single issuer URL. By rejecting unauthorized tenants before token generation, attribute conditions prevent the confused deputy problem and stop unauthorized token reuse.

Manage IAM Policies, Principal Identifiers, and Federated Sessions

Constructing Principal Identifiers

Google Cloud uses standardized principal identifiers to bind IAM roles directly to federated identities without storing user profiles. These identifiers are used in standard IAM commands, such as gcloud projects add-iam-policy-binding, to enable attribute-based access control (ABAC). Administrators grant permissions at various scopes using specific identifier patterns:

• Individual user: principal://iam.googleapis.com/locations/global/workforcePools/POOL_ID/subject/SUBJECT_ATTRIBUTE_VALUE
• Group membership: principalSet://iam.googleapis.com/locations/global/workforcePools/POOL_ID/group/GROUP_ID
• Specific custom attribute: principalSet://iam.googleapis.com/locations/global/workforcePools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE
• Entire pool: principalSet://iam.googleapis.com/locations/global/workforcePools/POOL_ID/*

Session Durations and Credential Lifecycle

Administrators control credential lifetimes by setting the session duration at the workforce pool level. This duration determines how long temporary access tokens, Cloud Console sessions, and Google Cloud CLI sessions remain valid. The configuration allows a range from 15 minutes (900 seconds) up to 12 hours (43,200 seconds), with a default lifetime of 1 hour (3,600 seconds). Shorter session windows reduce the risk of compromised tokens, while longer windows reduce re-authentication interruptions for users during active tasks.