Workforce Pools, Providers and Federated Access

Manage IAM policies, principal identifiers, and federated sessions is the practice of granting Google Cloud roles to external workforce users without creating Google Accounts for them. Workforce Identity Federation (opens in a new tab) authenticates employees, partners, and contractors in an external identity provider (IdP) with single sign-on using OpenID Connect (OIDC) or SAML 2.0. Authorization is then granted with IAM allow policies that address those federated identities by pool, subject, group, or attribute, while a pool-level session duration controls how long tokens and sign-in sessions remain valid.

1.1Workforce Principal Identifiers for IAM Allow Policies

Workforce principal identifiers are IAM member strings that address federated users in allow policies without synchronized Google identities. Each identifier contains the organization-level workforce identity pool ID and then narrows scope to one subject or to a set of identities. Identifiers that start with principal:// address exactly one identity, while identifiers that start with principalSet:// address a group, an attribute value, or the whole pool.

The SUBJECT_ATTRIBUTE_VALUE comes from the mapped google.subject attribute, while GROUP_ID and ATTRIBUTE_NAME/ATTRIBUTE_VALUE come from IdP claims mapped to google.groups or custom attributes. Because pools are configured at the Google Cloud organization level with a globally unique pool ID, the same identifier can be referenced by allow policies in any project or folder inside that organization.

1.2Constructing IAM Bindings with Pool, Group, and Attribute Scopes

Constructing IAM bindings for workforce pools means choosing the narrowest principal set that still covers the workforce that needs the role. A binding to the whole-pool /* principal set grants the role to every identity that can authenticate through the pool, so it fits only broadly shared access. A binding to group/GROUP_ID or attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE limits the role to users whose IdP group membership or mapped attribute matches, which supports attribute-based access and least privilege. A binding to a single subject/ principal addresses one user for break-glass access, admin delegation, or testing.

Distributed management uses separate pools to isolate ownership when different workforces need different administrators. For example, an enterprise can keep one pool for its own employees and create a separate partner pool for a partner organization, then grant roles/iam.workforcePoolEditor on the partner pool to the partner administrator. The partner administrator then connects their own IdP provider and manages group and attribute bindings inside that pool without gaining control over employee access.

1.3Session Duration and Short-Lived Token Exchange

Session duration is the pool-level lifetime that controls how long federated access remains valid before re-authentication is required. The same duration applies to three credential types from the pool:

• Google Cloud access tokens obtained through token exchange
• Console federated sign-in sessions through auth.cloud.google
• gcloud CLI sign-in sessions for the federated identity

The token flow follows OAuth 2.0 Token Exchange, where a credential flows from the external IdP to the Security Token Service, the Security Token Service verifies the identity in the credential, and the service returns a short-lived Google Cloud access token to the caller. Session duration defaults to one hour (3600s) and must be between 15 minutes (900s) and 12 hours (43200s), set with --session-duration when the pool is created and changeable later by updating the pool. A shorter duration reduces exposure from stolen tokens and stale group membership at the cost of more frequent sign-ins, while a longer duration improves usability for console and command-line work.

1.4Console and Command-Line Credential Lifecycles

Console and command-line credential lifecycles describe how a federated user obtains usable Google Cloud credentials after IdP authentication. For browser access, the user signs in through the console federated sign-in at auth.cloud.google using the provider resource name locations/global/workforcePools/POOL_ID/providers/PROVIDER_ID, and the IdP redirects back to the sign-in callback URL for that pool and provider. For programmatic access, the gcloud CLI exchanges an IdP token for a Google access token using a credential configuration file that points to the Security Token Service.

The gcloud CLI lifecycle proceeds in order:

1. Capture subject token: Save the OIDC ID token or SAML response from the IdP to a local file referenced as the credential source.
2. Generate configuration: Run gcloud iam workforce-pools create-cred-config with the pool provider audience, the subject token type, the token URL https://sts.googleapis.com/v1/token, and the workforce pools user project.
3. Log in and exchange: Run gcloud auth login --cred-file=config.json, after which gcloud transparently exchanges the IdP credential for temporary Google Cloud access tokens for subsequent calls.

The configuration depends on a workforce pools user project that identifies the application to Google APIs and serves as the default quota project for client-based APIs. The principal must have the serviceusage.services.use permission on that project, included in the Service Usage Consumer role, because some APIs bill and enforce quota against the client project rather than the resource project.

1.5Organization Trust Boundary and Delegated Pool Management

The organization trust boundary defines where workforce pool principals can directly act on resources. Workforce identity pool principals cannot directly access resources outside the organization that owns the pool, so a pool created in one organization does not grant access in another organization. That boundary depends on direct resource access, because IAM allow policies for those principals are evaluated inside the owning organization.

The boundary can be bypassed if a workforce principal is allowed to impersonate a service account inside the organization, since service accounts are not equally restricted across organizations. To contain that risk, grant service account impersonation only to narrowly scoped group or attribute principal sets and audit pool membership through Cloud Audit Logs by pool ID. Separate pools for employees, partners, or divisions further contain the blast radius by letting each pool owner grant roles only to identities in that pool.

Attribute mappings and assertion conditions control how external identities become Google Cloud identities in Workforce Identity Federation (opens in a new tab). Attribute mappings translate claims from an OIDC ID token or SAML 2.0 assertion into Google Cloud attributes using Common Expression Language (CEL). Attribute conditions are CEL boolean expressions that decide whether a user is allowed to sign in through a workforce identity pool provider at all.

2.1Attribute Mappings with CEL

Attribute mappings in a workforce identity pool provider define how data flows from the external IdP assertion to Google Cloud attributes. Each mapping pairs a Google-side key on the left with a CEL expression over the IdP assertion on the right, such as google.subject=assertion.oid or attribute.costcenter=assertion.costcenter. For OIDC, a top-level claim is referenced as assertion.PROPERTY_NAME, while SAML attributes often require indexing such as assertion.attributes['department'][0]. The total size of all mappings for a provider is limited to 16 KB, and the sign-in attempt fails if mappings exceed that limit.

The OIDC web sign-in flow affects how many claims are available for mapping. With authorization code flow, tokens travel in a secure backend transaction directly from the IdP to Google Cloud, so transactions can retrieve tokens of any size with more claims for mapping and conditions. With implicit flow, the ID token is returned from the IdP to the browser and is subject to browser URL size limits, which can restrict the claims available.

2.2Reserved Google Attributes and Custom Attributes

Reserved Google attributes are the standard targets that Security Token Service produces during token exchange from a workforce identity pool provider. google.subject is the required unique identifier for the user, is recorded as the principal in Cloud Audit Logs, and is used in IAM allow policies. google.groups is the optional group membership list, google.display_name sets the console display name, and google.profile_photo sets the console profile picture. Custom attributes with the prefix attribute. carry department, cost center, or other IdP values into Google Cloud for fine-grained IAM decisions.

The google.groups mapping needs extra care because every member of a mapped group inherits any IAM grant on that group. Group names should be limited to about 40 characters, and the assertion should include only groups used for Google Cloud federation to stay under the 400-group sign-in failure threshold. Only authorized administrators in the IdP should be able to change membership of mapped groups, since an unauthorized addition directly expands Google Cloud access. For the same reason, google.subject should not be an email address or other mutable value, because changing the value in the IdP directory causes the user to lose access to their prior principal.

2.3Attribute Conditions to Restrict Pool Access

Attribute conditions in a workforce identity pool provider are CEL expressions that gate sign-in before Google Cloud issues federated tokens. The condition evaluates the raw assertion fields and any mapped values, and the sign-in is blocked when the result is false. A condition such as assertion.role == 'gcp-users' allows only users with that role, assertion.subject.endsWith('@example.com') restricts sign-in to one email domain, and assertion.ipaddr.startsWith('98.11.12.') restricts sign-in by network risk context.

Attribute conditions also prevent the confused deputy problem by rejecting credentials intended for another platform. They are mandatory for multi-tenant IdPs that share one issuer URL across tenants, because issuer verification alone cannot prove which tenant issued the token. In that case the condition must check a tenant-specific claim, such as organization ID, tenant ID, or allowed role, so only the correct tenant can exchange tokens through that provider.

2.4Validating Mappings and Conditions

Validation in the Google Cloud console interactively tests how a real IdP token flows through mappings and the condition. The Validate your provider attributes viewer shows raw assertion JSON, the resulting mapped Google attributes, and the boolean condition result without completing end-user sign-in. The Mapped attributes section flags incorrect mappings with an error icon, and the Attribute condition section shows whether sign-in would be allowed or blocked.

The validation workflow runs in order:

1. Allow the callback: Add the sign-in callback URL for the pool and provider to the IdP allowed redirect URIs.
2. Open the pool: Go to Workforce Identity Pools and select the pool to verify.
3. Open the provider: Select the IdP provider in the pool details page.
4. Start debugging: Click Debug IdP token to open the sign-in dialog.
5. Sign in as test user: Authenticate to the IdP to fetch a real assertion.
6. Inspect results: Review mapped attributes, view the full token for raw assertion fields, and check the condition result.

If a mapping or condition is wrong, the validation page supports direct correction by editing the CEL, then choosing Save and refetch token to test the updated configuration with a fresh assertion.

Workforce Identity Federation is the Google Cloud mechanism for giving workforce users access without synchronizing their identities into Google Cloud. A workforce pool holds the trust configuration for an organization, and each external identity provider inside the pool connects one external identity system to Google Cloud. Workforce employees, partners, and contractors authenticate with their home provider, and Google Cloud then authorizes them to use the console, Google Cloud CLI, and APIs based on IAM policy.

3.1How Pools Establish Trust with External Providers

How pools establish trust defines the boundary between Google Cloud on one side and an external IdP on the other. The pool is configured in a Google Cloud project through the federation setup process, which links the external identity system to Google Cloud. Each provider inside the pool has a workforce pool provider name that identifies which external system the user belongs to during sign-in. Once that trust exists, external identities can be referenced directly in IAM policies without creating Google Accounts for them.

3.2Granting Google Cloud Access to Workforce Pool Users

Granting access to workforce pool users means representing external identities in IAM policies and binding them to roles. Representation can target a whole pool, a specific provider, or selected attributes and groups from the external system. Access then depends on role grants in the project, and the grant must exist before the user attempts the action. For example, access to the Managed Service for Apache Spark (opens in a new tab) Component Gateway depends on three ordered prerequisites:

1. Configure federation: Workforce Identity Federation is configured in the project.
2. Grant IAM role: External identity users are granted dataproc.clusters.use to authorize Component Gateway use.
3. Create the resource: A Managed Service for Apache Spark cluster is created with Component Gateway enabled.

3.3External Identity Access Flow and URL Behavior

The external identity access flow controls how an unauthenticated browser reaches a federated web interface such as Component Gateway. Component Gateway web interfaces run on the first master node of a Managed Service for Apache Spark cluster, and external identities use a dedicated URL of the form https://UNIQUE_ID-dot-dataproc.byoid.googleusercontent.com. Only users authenticated with external identities can access the URL for external identities. Traffic flows first from the user browser to the URL, then to the authentication portal where the user specifies the workforce pool provider name, then to the external IdP for sign-in, and finally back to the component web interface.

Federated access covers most Managed Service for Apache Spark console, CLI, and API features, but the documentation excludes specific areas:

• Managed Service for Apache Spark on GKE
• Managed Service for Apache Spark Personal Authentication
• Managed Service for Apache Spark Service Account Based Secure Multi-tenancy
• The Output section in Batch and Job details pages and the Recommended Alerts section in Cluster and Job list pages in the Google Cloud console

Key Facts

• Workforce principal identifiers use principal:// for exactly one federated subject and principalSet:// for a group, an attribute value, or the whole pool with /*.
• Workforce pool session duration defaults to one hour and must be between 15 minutes and 12 hours, controlling access tokens, console federated sessions, and gcloud CLI sessions.
• Workforce identity pool principals cannot directly access resources outside the organization that owns the pool unless they impersonate a service account inside that organization.
• Attribute mappings translate IdP claims into Google attributes with CEL, where google.subject and google.groups can control IAM access but google.display_name and google.profile_photo are console-only.
• Component Gateway access for federated users requires the dataproc.clusters.use role and the dedicated byoid.googleusercontent.com URL for external identities.