SAML Federation and OAuth for Workforce Access

SAML 2.0 federation for workforce identity lets an external identity provider (IdP) (opens in a new tab) authenticate users while Google acts as the service provider that grants access to Google services. Trust is established by exchanging identifiers, endpoints, and signing certificates, and then mapping the SAML assertion to a Google identity. When logins fail, the fault is isolated by decoding the outbound SAML request and the inbound SAML response and comparing each field to the configuration on both sides.

1.1How SAML Federation Divides Authentication Work

How SAML federation divides authentication work describes three roles that cooperate so the user signs in once at the IdP and gains access without a separate Google password. The principal requests access to the service provider, the service provider redirects that request to the IdP for authentication, and the IdP returns a signed assertion that the service provider uses to create the session or OAuth 2.0 token required for access. The user is then redirected to the target application or console.

SAML federation divides work among three entities:

• Principal: the user trying to sign in and requesting access
• Service provider: the Google-operated system the user wants to use
• External IdP: the third-party system that supports SAML 2.0 and authenticates the user

SAML in this exchange performs authentication only, while authorization remains controlled separately by Google IAM roles, Cloud Identity or Google Workspace account state, or application roles.

1.2Establishing Trust Between Google and the External Identity Provider

Establishing trust between Google and the external IdP means each side stores verifiable identifiers for the other side so requests and responses are accepted only from the expected partner. On the Google side, Identity Platform (opens in a new tab), Cloud Identity, or Google Workspace stores the IdP entity ID, the IdP SAML single sign-on (SSO) URL, and the IdP token-signing certificate including its -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines. On the IdP side, the administrator registers Google as the relying party by configuring the service-provider entity ID that acts as the audience, the Assertion Consumer Service (ACS) URL where the IdP must post the response, and the expected issuer and audience values.

The trust configuration depends on four related pieces of data that must match on both sides:

• IdP entity ID: the globally unique identifier for the external IdP, stored in the Google SAML profile and sent by the IdP in responses
• SAML SSO URL and sign-in, sign-out, and password URLs: the IdP endpoints where Google sends authentication requests and where users are sent for sign-out or password change
• Verification certificate: the IdP token-signing public certificate that Google uses to validate assertion signatures, which must be rotated before it expires
• Service-provider entity ID and ACS URL: the Google audience identifier, typically the application URL, and the Google callback URL that the IdP must use as the reply destination

If any of these four values differ between Google and the IdP, Google rejects the request or the IdP posts the response to the wrong destination.

1.3Mapping SAML Assertions to Google Identities and Attributes

Mapping SAML assertions to Google identities converts the IdP NameID and attribute statements into the Google subject and attribute names used for access decisions. Google expects a stable subject derived from the assertion subject, commonly expressed in a workforce identity pool as google.subject = assertion.subject, with additional attributes mapped explicitly such as attribute.user_email, attribute.first_name, attribute.last_name, and google.groups from the corresponding assertion attributes. The left side of each mapping uses fixed Google syntax, while the right side references the claim names actually sent by the IdP, including array indexing such as assertion.attributes.user_email[0] when the IdP sends multi-valued attributes. To minimize assertion size, the IdP should send only attributes required by Google Sign-In, because extra profile data that is not mapped is not used when the Cloud Identity or Google Workspace account is the source for user information.

Name identifier format is a frequent source of mismatch because the IdP can source the Unique User Identifier (NameID) in different ways. One pattern maps NameID directly from user.mail and deletes unneeded additional claims, which works when mail already matches the provisioned Google identity. Another pattern builds NameID with transformations, first applying ExtractMailPrefix() to user.userPrincipalName and then applying Join() with separator @ and a substitute verified domain, which must use the same substitute domain for both provisioning and single sign-on. Provider configuration adds a related naming rule: a custom SAML provider ID in Identity Platform must begin with saml.

1.4Issuer and Audience Alignment for Google Sessions

Issuer and audience alignment controls whether the IdP recognizes Google requests and whether Google accepts IdP responses across all Google services. By default Google uses google.com as the Issuer element in SAML requests and expects google.com as the Audience element in SAML responses, which reflects that one Google Sign-In session is valid across services the user can access. The alternative is a domain-specific issuer that uses google.com/a/DOMAIN, where DOMAIN is the primary domain of the Cloud Identity or Google Workspace account.

1.5Troubleshooting Certificate, ACS, and NameID Failures

Troubleshooting certificate, ACS, and NameID failures follows the ordered flow of data from Google to the IdP and back to Google, so each decoded message reveals which side holds the wrong value. Capture begins in a clean browser window with Developer Tools open on the Network tab and Preserve log selected, then the login flow is started from the Google URL so redirects are not lost. The outbound request appears as a SAMLRequest query parameter and the inbound response appears as a SAMLResponse posted to the signin-callback endpoint, and each value can be copied into a SAML decoding tool and, for token contents, a JWT inspection tool.

Validate the exchange in order to isolate certificate, endpoint, and identity-mapping errors:

1. Prepare capture: Open an Incognito window, open Developer Tools, select the Network tab, select Preserve log, then navigate to the Google environment URL to start login.
2. Validate the SAML request to the IdP: Filter network traffic for saml, open the Payload tab to copy SAMLRequest, decode it, then check Request Destination and confirm that destination URL exactly matches the SSO configuration stored in the IdP.
3. Validate the SAML response from the IdP: Filter network traffic for signin-callback, open the Payload tab to copy SAMLResponse, decode it, then review claims for groups, first name, last name, and email and confirm each claim name and value matches the attribute mapping in the workforce pool and the expected user.
4. Resolve trust and mapping mismatches: Replace an expired or incorrectly pasted IdP verification certificate, correct the ACS reply URL and IdP entity ID on the side that does not match, and fix NameID sourcing so the returned subject equals the provisioned Google identity, including correcting transformation parameters or switching between user.mail and transformed user principal name.

A request-destination mismatch points to a wrong SSO URL or ACS configuration in the IdP, a signature failure points to a missing, truncated, or expired token-signing certificate on the Google side, and a successful signature with denied access points to a NameID or attribute-name mismatch between the assertion and the workforce pool mapping.

Implementing OAuth 2.0 flows for secure application and API authorization in Workforce Identity Federation (opens in a new tab) lets federated users sign in with their external identity provider to access Google Cloud through OAuth-based applications. The integration depends on a workforce identity pool and provider that must be created first, and the application must be registered in the same organization where that pool and provider are configured. OAuth application integration in this model works only with Identity-Aware Proxy (IAP), so applications outside IAP cannot use this path.

2.1Prerequisites and Application Registration for Workforce OAuth

Prerequisites and application registration for Workforce OAuth define what must exist before a federated user can obtain an access token for Google Cloud. The application depends on the workforce identity pool and provider for federated sign-in, and registration creates an OAuth client whose credential contains a client secret. After registration, data flows from the IdP-authenticated user to the application and then to Google Cloud, as the application uses the access token to access Google Cloud products and data on behalf of the federated user.

Workforce OAuth clients are distinct from standard Google OAuth clients, and choosing the wrong management path breaks the configuration:

The projects.locations.oauthClients API is only for Workforce Identity Federation, while standard OAuth 2.0 client IDs are created and managed under APIs & Services > Credentials.

2.2Securing Client IDs, Secrets, and Credential Rotation

Securing client IDs, secrets, and credential rotation restricts who can view or manage the OAuth client ID, client secret, and the IAM APIs that control them. The OAuth client ID and secret form a trust boundary because anyone who holds them can present a copy of the application to users and to Google Cloud. Access to the OAuth client and credential API must therefore be granted only to trusted users, since leakage of the secret allows abuse of the permissions the legitimate application holds.

If the client ID and secret leak, the documented impacts are impersonation of the legitimate application and reputational damage to the application and organization. Impersonation by a malicious user with the client ID and secret can take several forms:

• Gain unauthorized access to the user data and permissions that the legitimate application is entitled to
• Perform actions on the user's behalf, such as posting content, making API calls, or modifying user settings
• Perform phishing attacks with a fake login page that resembles the OAuth provider to trick users into entering credentials

When a breach is suspected, the response is to assess the nature of the breach and rotate the client secret immediately so the exposed credential can no longer be used. Rotation follows an ordered lifecycle where the new credential is established before the old credential is removed:

1. Create a new client credential for the OAuth client so the legitimate application has a working secret
2. Disable the old client credential so the leaked secret can no longer obtain access
3. Delete the old client credential only after the replacement is in use to complete removal

Differentiating between SAML and OAuth 2.0 protocols means contrasting their core purposes and choosing the right one for workforce identity versus API access. Security Assertion Markup Language (SAML) (opens in a new tab) is an open standard for web-based single sign-on and identity federation, while OAuth 2.0 is a token-based framework for delegated authorization and API access. In Google Cloud the two protocols divide responsibility: SAML proves who the user is through an external identity provider, and OAuth 2.0 provides the token that actually grants access to an application or API.

3.1SAML for Web-Based Single Sign-On and Identity Federation

SAML for web-based single sign-on and identity federation lets an identity provider pass authorization credentials to a service provider as a signed identity assertion. The SAML specification defines three entities that participate in every exchange: the principal who is requesting access, the service provider that the user wants to use, and the identity provider that authenticates the user. When SAML is enabled for Apigee, Google Cloud Platform acts as the SAML service provider and the third-party provider such as Active Directory or Microsoft Entra ID (formerly Azure AD) acts as the identity provider.

The SAML flow moves trust from the enterprise directory to Google. The principal first requests access to the service provider, then Google Cloud Platform in its role as SAML service provider requests and obtains an identity assertion from the third-party SAML identity provider and uses that assertion to create the OAuth 2.0 token required to access the Apigee UI. The user is then redirected to the Apigee UI, so one central login produces access without a separate Google password.

3.2OAuth 2.0 for Delegated Authorization and API Access

OAuth 2.0 for delegated authorization and API access issues scoped tokens that let an application act on a user's behalf without sharing the user's credentials. In the Apigee pattern, the SAML assertion itself does not open the UI; Google Cloud Platform uses that assertion to create the OAuth 2.0 token required to access the Apigee UI, and that token is what the UI and APIs check. A similar handoff appears for web applications that bridge SAML and login: a SAML token is posted to the Google sign-in endpoint, and the Google sign-in endpoint then completes the login and issues OpenID Connect tokens to the web application.

This token layer creates a clear authentication versus authorization boundary. SAML authentication offers centralized user management, control over how users authenticate, control over authentication policies, and monitoring of logins, logouts, unsuccessful attempts, and high-risk activity. Authorization after authentication is still controlled separately, such as by Apigee user roles for the Apigee UI and by IAM grants for Google Cloud resources, so deprovisioning a user centrally denies future SAML logins while roles determine what any valid token can do.

3.3How SAML and OAuth 2.0 Work Together in Google Cloud

How SAML and OAuth 2.0 work together in Google Cloud is a two-stage chain in which federation authenticates the user and OAuth-based tokens authorize access. First, federation of Cloud Identity or Google Workspace with an external identity provider provisions user accounts from an external authoritative source and lets users authenticate to Google services through the external provider using SAML. Second, the successful SAML exchange results in Google sessions and OAuth-based tokens that apply across services the user has been granted access to, including the Google Cloud console as well as the Google Cloud CLI and other API clients through the Google Cloud session.

SAML configuration in this chain centers on trust between provider and service. In Identity Platform (opens in a new tab), a SAML provider requires a provider ID beginning with saml, the provider Entity ID, the SAML SSO URL, and the token-signing certificate, while the service provider side defines the app Entity ID used as the audience and the authorized app domain. For Google Sign-In federation, Google by default uses google.com as the issuer in SAML requests and expects google.com as the audience in SAML responses, switching to google.com/a/DOMAIN only when the domain-specific issuer option is enabled to distinguish multiple Cloud Identity or Google Workspace accounts.

3.4Choosing Between Workforce Identity and API Access

Choosing between workforce identity and API access means matching the protocol to whether the goal is central lifecycle control or limited, revocable access to a specific resource. Workforce identity scenarios favor SAML because the goal is to let employees use one enterprise credential for many Google services with central lifecycle control. Choose SAML federation when the enterprise must automatically provision relevant accounts to Cloud Identity or Google Workspace, designate the external provider as the source of truth, propagate suspension and deletion events, and automatically deny access when users leave and are deprovisioned centrally.

API and application access scenarios favor OAuth 2.0 tokens because the goal is to grant limited access without reusing the enterprise password at each resource. Choose OAuth 2.0 tokens when Apigee UI access, Identity Platform application sign-in, or Google Cloud console, CLI, and API calls must proceed without sharing user credentials. Best practice in the SAML model is to minimize attributes to only those required by Google Sign-In, keep the default google.com issuer unless multiple domains require separation, and align session lengths so the identity provider session is shorter than the Google session to avoid silent re-authentication.

The default Google services session length is 14 days, changeable to periods such as 8 hours with Cloud Identity Premium or Google Workspace Business, while Google Admin console sessions have a fixed length of 1 hour that cannot be customized.

Key Facts

• SAML 2.0 federation for workforce identity uses Google as the service provider and an external identity provider for authentication, with Google accepting the response only when the IdP entity ID, SSO URL, verification certificate, service-provider entity ID, and Assertion Consumer Service URL match on both sides.
• Google uses google.com as the default SAML issuer and expected audience, and uses google.com/a/DOMAIN only when multiple Cloud Identity or Google Workspace accounts require the identity provider to distinguish sign-ons.
• OAuth application integration for Workforce Identity Federation requires a workforce identity pool and provider in the same organization and works only with Identity-Aware Proxy, using workforce OAuth clients managed separately from standard OAuth 2.0 client IDs.
• A leaked OAuth client secret requires immediate rotation in order: create a new client credential, disable the old client credential, then delete the old credential only after the replacement is in use.
• SAML provides authentication through signed identity assertions for workforce single sign-on, while OAuth 2.0 provides delegated authorization through access tokens for Apigee UI, web application, and Google Cloud API access without sharing user credentials.