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

Source: https://startwithidentity.com/recipes/gcp-workforce-identity-federation/
Last updated: 2026-11-05
License: content by Start with Identity. Cite the source URL.

---

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](https://startwithidentity.com/glossary/oidc/) or [SAML](https://startwithidentity.com/glossary/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](https://docs.cloud.google.com/iam/docs/workforce-identity-federation) as sync-less, so there is no Google Cloud Directory Sync to run.

This is the Google Cloud leg of a multi-cloud [federation](https://startwithidentity.com/glossary/federation/) design. The AWS leg is in [federate AWS IAM Identity Center with your IdP](https://startwithidentity.com/recipes/aws-iam-identity-center-federation/), and the decisions that span both are in the [multi-cloud IAM strategy guide](https://startwithidentity.com/guides/implementation/multi-cloud-iam-strategy-guide/).

## Before you start

| Decision | Recommendation |
| --- | --- |
| Workforce vs. workload | Workforce is for humans. CI jobs and workloads use [workload identity federation](https://startwithidentity.com/glossary/workload-identity-federation/) instead. |
| Workforce vs. Cloud Identity SSO | If users already have Google accounts through Workspace, SSO for those accounts is a separate feature. Workforce pools avoid Google accounts entirely. |
| OIDC or SAML | Either works. OIDC with the code flow is simpler to debug. Pick SAML if your IdP team standardizes on it. |
| Session length | Default is 1 hour. Allowed range is 900s to 43200s (15 minutes to 12 hours). |

Workforce principals [can't directly access resources outside their organization](https://docs.cloud.google.com/iam/docs/workforce-identity-federation), 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.

```bash
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](https://docs.cloud.google.com/iam/docs/manage-workforce-identity-pools-providers) for 30 days with `gcloud iam workforce-pools undelete`.

## 2. Register Google Cloud in the IdP

For [Microsoft Entra](https://startwithidentity.com/vendors/iam/microsoft-entra/) with OIDC, follow [Google's Entra ID guide](https://docs.cloud.google.com/iam/docs/workforce-sign-in-microsoft-entra-id): **Entra ID > App registrations > New registration**, platform **Web**, and this redirect URI:

```text
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](https://startwithidentity.com/vendors/iam/okta/), [Google's Okta guide](https://docs.cloud.google.com/iam/docs/workforce-sign-in-okta) 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.

```bash
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](https://docs.cloud.google.com/iam/docs/workforce-identity-federation) 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.

```bash
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](https://startwithidentity.com/glossary/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`:

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

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

```bash
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](https://docs.cloud.google.com/iam/docs/workforce-sign-in-microsoft-entra-id), 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](https://startwithidentity.com/recipes/aws-iam-identity-center-federation/)
- [Multi-cloud IAM strategy guide](https://startwithidentity.com/guides/implementation/multi-cloud-iam-strategy-guide/)
- [Federation](https://startwithidentity.com/glossary/federation/), [OIDC](https://startwithidentity.com/glossary/oidc/), [SAML](https://startwithidentity.com/glossary/saml/)
- [Workload identity federation](https://startwithidentity.com/glossary/workload-identity-federation/) (for CI and workloads, not people)
- [GitHub Actions OIDC to AWS and Azure](https://startwithidentity.com/recipes/github-actions-oidc-aws-azure/)