Set up Google Cloud Workforce Identity Federation with Entra ID or Okta

Workforce Identity Federation lets people in Microsoft Entra ID or Okta sign in to Google Cloud with single sign-on and receive IAM roles directly, with no copies of the users in Cloud Identity or Google Workspace. You create a workforce pool at the organization level, add one OIDC or SAML provider that trusts your IdP, map the IdP's subject and groups claims, and grant roles to group-based principal identifiers. The end state: a user opens the federated sign-in URL, authenticates at the IdP, and lands in the console or gcloud with exactly the roles their groups carry. Google describes the service as sync-less, so there is no Google Cloud Directory Sync to run.

This is the Google Cloud leg of a multi-cloud federation design. The AWS leg is in federate AWS IAM Identity Center with your IdP, and the decisions that span both are in the multi-cloud IAM strategy guide.

Before you start

Workforce principals can't directly access resources outside their organization, and the overview requires Essential Contacts because these users have no Cloud Identity email address. Check the supported products list linked from that page before you migrate a team.

1. Create the workforce pool

The pool lives at the organization, and its location is always global. Pool IDs must be unique across all workforce pools.

gcloud iam workforce-pools create corp-pool \
    --organization=ORGANIZATION_ID \
    --display-name="Corporate IdP" \
    --description="Entra ID workforce federation" \
    --session-duration=28800s \
    --location=global

Check: gcloud iam workforce-pools describe corp-pool --location=global returns the pool with sessionDuration: 28800s. Common failure: PERMISSION_DENIED means you hold the role on a project, not the organization. Grant roles/iam.workforcePoolAdmin at the organization node. Rollback: gcloud iam workforce-pools delete corp-pool --location=global. Deleted pools can be undeleted for 30 days with gcloud iam workforce-pools undelete.

2. Register Google Cloud in the IdP

For Microsoft Entra with OIDC, follow Google's Entra ID guide: Entra ID > App registrations > New registration, platform Web, and this redirect URI:

https://auth.cloud.google/signin-callback/locations/global/workforcePools/corp-pool/providers/entra-oidc

Add a groups claim (Add groups claim), then create a client secret under Certificates & secrets if you will use the code flow. For SAML, use Enterprise applications > New application > Create your own application, set the Entity ID to the iam.googleapis.com/locations/global/workforcePools/corp-pool/providers/entra-saml form the guide gives, and download the federation metadata XML.

For Okta, Google's Okta guide uses the same redirect URI. On the org authorization server, set the groups claim filter in the app's Sign On tab to Matches regex .*; on a custom authorization server, add a groups claim to the ID token.

Check: the Entra OpenID metadata document (https://login.microsoftonline.com/TENANT_ID/v2.0/.well-known/openid-configuration) shows an issuer value. Copy it exactly. Common failure: a redirect URI that names a different pool or provider ID than you create in step 3. The sign-in fails at the callback. Rollback: delete the app registration or Okta app integration.

3. Create the provider with attribute mapping

google.subject is required, must be at most 127 bytes, and should be immutable. For Entra, Google recommends the object ID (oid), not the email.

gcloud iam workforce-pools providers create-oidc entra-oidc \
    --workforce-pool=corp-pool \
    --issuer-uri="https://login.microsoftonline.com/TENANT_ID/v2.0" \
    --client-id="APP_CLIENT_ID" \
    --client-secret-value="APP_CLIENT_SECRET" \
    --web-sso-response-type="code" \
    --web-sso-assertion-claims-behavior="merge-user-info-over-id-token-claims" \
    --vendor-type="entra-id" \
    --attribute-mapping="google.subject=assertion.oid,google.groups=assertion.groups,google.display_name=assertion.preferred_username" \
    --location=global

For SAML, swap to create-saml with --idp-metadata-path=metadata.xml and map google.subject to the objectidentifier claim. For Okta, use --vendor-type="okta", and pass --web-sso-additional-scopes="groups" so groups arrive at browser sign-in.

Add --attribute-condition to restrict who can sign in, for example assertion.subject.endsWith('@example.com') from the Okta guide. Google requires a condition when the IdP is multi-tenant with a single issuer URI.

Check: gcloud iam workforce-pools providers describe entra-oidc --workforce-pool=corp-pool --location=global shows your issuer URI and attribute mapping. Common failure: sign-in fails for users in many groups. The standard Entra setup maps up to 150 groups, Google documents a separate method for up to 400, and users in more than 400 groups can't sign in. Rollback: gcloud iam workforce-pools providers delete entra-oidc --workforce-pool=corp-pool --location=global (undeletable for 30 days).

4. Grant IAM roles to groups

Grant roles to the group principal set, not to individuals. GROUP_ID is the exact value your IdP puts in the groups claim, so decode a token before you write bindings.

gcloud projects add-iam-policy-binding test-project \
    --role="roles/viewer" \
    --member="principalSet://iam.googleapis.com/locations/global/workforcePools/corp-pool/group/GROUP_ID"

A single user is principal://iam.googleapis.com/locations/global/workforcePools/corp-pool/subject/SUBJECT_VALUE, which is useful for a break-glass test account. Mapped attributes work too, for example .../workforcePools/corp-pool/attribute.department/DEPARTMENT_VALUE.

Check: gcloud projects get-iam-policy test-project lists the principalSet:// member. Common failure: the user signs in but sees no projects. The group value in the binding does not match the claim, often a display name in one place and an object ID in the other. Rollback: gcloud projects remove-iam-policy-binding with the same role and member.

5. Configure console and gcloud sign-in

Users start at the federated sign-in URL and enter the provider name locations/global/workforcePools/corp-pool/providers/entra-oidc:

https://auth.cloud.google/signin?continueUrl=https://console.cloud.google/

For the CLI, generate a login configuration file and distribute it:

gcloud iam workforce-pools create-login-config \
    locations/global/workforcePools/corp-pool/providers/entra-oidc \
    --output-file=wf-login.json --activate
gcloud auth login --login-config=wf-login.json

Check: gcloud auth list shows the federated principal as active. Common failure: users tamper with or replace the file. Google notes that the login config isn't validated, so ship it read-only through device management. Rollback: delete the file and sign in with gcloud auth login using a non-federated account.

Verify it works

1. In a private browser window, open the sign-in URL above, enter the provider name, and authenticate as a test user in the granted group. You should land in the console and see test-project.
2. From the CLI, run gcloud projects list after gcloud auth login --login-config=wf-login.json. Only projects bound to the user's groups appear.
3. Remove the test user from the IdP group, sign in again after the session expires, and confirm access is gone. That is your deprovisioning test.
4. In Cloud Audit Logs, filter for the pool ID. Workforce sign-ins and API calls are logged with the pool, so you can attribute actions to IdP subjects.

Related

• Federate AWS IAM Identity Center with your IdP
• Multi-cloud IAM strategy guide
• Federation, OIDC, SAML
• Workload identity federation (for CI and workloads, not people)
• GitHub Actions OIDC to AWS and Azure