This guide describes how to configure Workforce Identity Federation with anidentity provider (IdP) that supportsOIDCorSAML 2.0.

For IdP-specific instructions, see the following:

• Configure Microsoft Entra ID-based Workforce Identity Federation
• Configure Okta-based Workforce Identity Federation

Before you begin

1. Make sure that you have a Google Cloud organization set up.

2. Install the Google Cloud CLI. After installation,initialize the Google Cloud CLI by running the following command:

   gcloudinit

   If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

   Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update.

3. Enable the Identity and Access Management (IAM) and Resource Manager APIs.

   Roles required to enable APIs

   To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enable permission.Learn how to grant roles.

   Enable the APIs

4. For sign-in, your IdP must provide signed authentication information:OIDC IdPs must provide a JWT, and SAML IdP responses must be signed.
5. To receive important information about changes to your organization orGoogle Cloud products, you must provideEssential Contacts.For more information, see theWorkforce Identity Federation overview.

Costs

Workforce Identity Federation is availableas a no-cost feature. However, Workforce Identity Federation detailed audit logging uses Cloud Logging. To learn about Logging pricing,seeGoogle Cloud Observability pricing.

Required roles

To get the permissions that you need to configure Workforce Identity Federation, ask your administrator to grant you theWorkforce Identity Pool Admin (roles/iam.workforcePoolAdmin) IAM role on the organization. For more information about granting roles, seeManage access to projects, folders, and organizations.

You might also be able to get the required permissions throughcustom roles or otherpredefined roles.

Alternatively, the Owner basic role (roles/owner) alsoincludes permissions to configure Workforce Identity Federation.You should not grant basic roles in a production environment, but you can grant them in adevelopment or test environment.

Configure Workforce Identity Federation

To configure Workforce Identity Federation, you create aworkforce identity pooland aworkforce identity pool provider.

Create a workforce identity pool

To create the pool, execute the following command:

gcloudiamworkforce-poolscreateWORKFORCE_POOL_ID\--organization=ORGANIZATION_ID\--display-name="DISPLAY_NAME"\--description="DESCRIPTION"\--session-duration=SESSION_DURATION\--location=global

Create a workforce identity pool provider

This section describes how to create aworkforce identity pool providerto enable your IdP users to access Google Cloud. You can configure the provider to use either the OIDC or SAML protocol.

Create an OIDC workforce pool provider

To create a workforce identity pool provider using the OIDC protocol, do thefollowing:

1. In your OIDC IdP, register a new application for Google CloudWorkforce Identity Federation. Note the client ID and issuer URIprovided by the IdP. You use them in this document.

2. If you plan to set up user access to the console, add the followingredirect URL to your OIDC IdP:

   https://auth.cloud.google/signin-callback/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID

   Replace the following:

   • WORKFORCE_POOL_ID: the workforce identity pool ID

   • WORKFORCE_PROVIDER_ID: the ID of the workforceidentity pool provider that you create later in this document.

   To learn how to configure console (federated) sign-in, seeSet up user access to the console (federated).

3. In Google Cloud, to create the provider, do the following:

   gcloud

   Code flow

   To create an OIDC provider that usesauthorization code flowfor web sign-in, run the following command:

   gcloud iam workforce-pools providers create-oidcWORKFORCE_PROVIDER_ID \    --workforce-pool=WORKFORCE_POOL_ID \    --display-name="DISPLAY_NAME" \    --description="DESCRIPTION" \    --issuer-uri="ISSUER_URI" \    --client-id="OIDC_CLIENT_ID" \
       --client-secret-value="OIDC_CLIENT_SECRET" \    --web-sso-response-type="code" \    --web-sso-assertion-claims-behavior="merge-user-info-over-id-token-claims" \    --web-sso-additional-scopes="WEB_SSO_ADDITIONAL_SCOPES" \    --attribute-mapping="ATTRIBUTE_MAPPING" \    --attribute-condition="ATTRIBUTE_CONDITION" \    --jwk-json-path="JWK_JSON_PATH" \    --detailed-audit-logging \    --location=global

   Replace the following:

   • WORKFORCE_PROVIDER_ID: A unique workforce identity pool provider ID. The prefixgcp- is reserved and can't be used in a workforce identity pool or workforce identity pool provider ID.
   • WORKFORCE_POOL_ID: The workforce identity pool ID to connect your IdP to.
   • DISPLAY_NAME: An optional user-friendly display name for the provider; for example,idp-eu-employees.
   • DESCRIPTION: An optional workforce provider description; for example,IdP for Partner Example Organization employees.
   • ISSUER_URI: The OIDC issuer URI, in a valid URI format, that starts withhttps; for example,https://example.com/oidc. Note: For security reasons,ISSUER_URI must use the HTTPS scheme.
   • OIDC_CLIENT_ID: The OIDC client ID that is registered with your OIDC IdP; the ID must match theaud claim of the JWT that is issued by your IdP.
   • OIDC_CLIENT_SECRET: The OIDC client secret.
   • WEB_SSO_ADDITIONAL_SCOPES: Optional additional scopes to send to the OIDC IdP for console (federated) or gcloud CLI browser-based sign-in.
   • ATTRIBUTE_MAPPING: Anattribute mapping. The following is an example of an attribute mapping:

     google.subject=assertion.oidgoogle.groups=assertion.groups,attribute.costcenter=assertion.costcenter

     This example maps the IdP attributesassertion.oid,assertion.groups, andassertion.costcenter in the OIDC assertion to the Google Cloud attributesgoogle.subject,google.groups, andattribute.costcenter,respectively.
   • ATTRIBUTE_CONDITION: Anattribute condition; for example,assertion.role == 'gcp-users'. This example condition ensures that only users with the rolegcp-users can sign in using this provider.Warning: If your multi-tenant IdP has a single issuer URI, you must useattribute conditions to ensure that access is restricted to the correct tenant. For more information, seeUse attribute conditions when federating with GitHub or other multi-tenant identity providers.
   • JWK_JSON_PATH: An optional path to alocally uploaded OIDC JWKs. If this parameter isn't supplied, Google Cloud instead uses your IdP's/.well-known/openid-configuration path to source the JWKs containing the public keys. For more information about locally uploaded OIDC JWKs, seemanage OIDC JWKs.Note: Local OIDC JWKs can be uploaded throughimplicit flow or code flow, but can only be used inprogrammatic flow, in which you directly call the STS/token endpoint with a credential from the third-party IdP to exchange for a Google Cloud access token for your workforce pool. You can't use local OIDC JWKs when signing in to the console (federated).

   • Workforce Identity Federationdetailed audit logging logs information received from your IdP to Logging. Detailed audit logging can help you troubleshoot your workforce identity pool provider configuration. To learn how to troubleshoot attribute mapping errors with detailed audit logging, seeGeneral attribute mapping errors. To learn about Logging pricing, seeGoogle Cloud Observability pricing.

     To disable detailed audit logging for a workforce identity pool provider, omit the--detailed-audit-logging flag when you rungcloud iam workforce-pools providers create. To disable detailed audit logging, you can alsoupdate the provider.

   In the command response,POOL_RESOURCE_NAME is the name of the pool;for example,locations/global/workforcePools/enterprise-example-organization-employees.

   Implicit flow

   To create an OIDC provider that uses theimplicit flowfor web sign-in, run the following command:

   gcloud iam workforce-pools providers create-oidcWORKFORCE_PROVIDER_ID \    --workforce-pool=WORKFORCE_POOL_ID \    --display-name="DISPLAY_NAME" \    --description="DESCRIPTION" \    --issuer-uri="ISSUER_URI" \    --client-id="OIDC_CLIENT_ID" \    --web-sso-response-type="id-token" \    --web-sso-assertion-claims-behavior="only-id-token-claims" \    --web-sso-additional-scopes="WEB_SSO_ADDITIONAL_SCOPES" \    --attribute-mapping="ATTRIBUTE_MAPPING" \    --attribute-condition="ATTRIBUTE_CONDITION" \    --jwk-json-path="JWK_JSON_PATH" \    --detailed-audit-logging \    --location=global

   Replace the following:

   • WORKFORCE_PROVIDER_ID: A unique workforce identity pool provider ID. The prefixgcp- is reserved and can't be used in a workforce identity pool or workforce identity pool provider ID.
   • WORKFORCE_POOL_ID: The workforce identity pool ID to connect your IdP to.
   • DISPLAY_NAME: An optional user-friendly display name for the provider; for example,idp-eu-employees.
   • DESCRIPTION: An optional workforce provider description; for example,IdP for Partner Example Organization employees.
   • ISSUER_URI: The OIDC issuer URI, in a valid URI format, that starts withhttps; for example,https://example.com/oidc. Note: For security reasons,ISSUER_URI must use the HTTPS scheme.
   • OIDC_CLIENT_ID: The OIDC client ID that is registered with your OIDC IdP; the ID must match theaud claim of the JWT that is issued by your IdP.
   • WEB_SSO_ADDITIONAL_SCOPES: Optional additional scopes to send to the OIDC IdP for console (federated) or gcloud CLI browser-based sign-in.
   • ATTRIBUTE_MAPPING: Anattribute mapping. The following is an example of an attribute mapping:

     google.subject=assertion.oidgoogle.groups=assertion.groups,attribute.costcenter=assertion.costcenter

     This example maps the IdP attributesassertion.oid,assertion.groups, andassertion.costcenter in the OIDC assertion to the Google Cloud attributesgoogle.subject,google.groups, andattribute.costcenter,respectively.
   • ATTRIBUTE_CONDITION: Anattribute condition; for example,assertion.role == 'gcp-users'. This example condition ensures that only users with the rolegcp-users can sign in using this provider.Warning: If your multi-tenant IdP has a single issuer URI, you must useattribute conditions to ensure that access is restricted to the correct tenant. For more information, seeUse attribute conditions when federating with GitHub or other multi-tenant identity providers.
   • JWK_JSON_PATH: An optional path to alocally uploaded OIDC JWKs. If this parameter isn't supplied, Google Cloud instead uses your IdP's/.well-known/openid-configuration path to source the JWKs containing the public keys. For more information about locally uploaded OIDC JWKs, seemanage OIDC JWKs.Note: Local OIDC JWKs can be uploaded throughimplicit flow or code flow, but can only be used inprogrammatic flow, in which you directly call the STS/token endpoint with a credential from the third-party IdP to exchange for a Google Cloud access token for your workforce pool. You can't use local OIDC JWKs when signing in to the console (federated).

   • Workforce Identity Federationdetailed audit logging logs information received from your IdP to Logging. Detailed audit logging can help you troubleshoot your workforce identity pool provider configuration. To learn how to troubleshoot attribute mapping errors with detailed audit logging, seeGeneral attribute mapping errors. To learn about Logging pricing, seeGoogle Cloud Observability pricing.

     To disable detailed audit logging for a workforce identity pool provider, omit the--detailed-audit-logging flag when you rungcloud iam workforce-pools providers create. To disable detailed audit logging, you can alsoupdate the provider.

   In the command response,POOL_RESOURCE_NAME is the name of the pool;for example,locations/global/workforcePools/enterprise-example-organization-employees.

   The prefixgcp- is reserved and can't be used in a workforce identity pool or workforce identity pool provider ID.

   For OIDC federation, you can useassertion.NAME: a string equalto the value of the like-named claim in the ID token payload.

   Console

   Code flow

   In the Google Cloud console, to create an OIDC provider thatusesauthorization code flow,do the following:

   1. In the Google Cloud console, go to theWorkforce Identity Pools page:

      Go to Workforce Identity Pools

   2. In theWorkforce Identity Pools table, select the pool for whichyou want to create the provider.

   3. In theProviders section,clickaddAdd Provider.

   4. In theSelect a Provider vendor list, select your IdP.

      If your IdP isn't listed, then selectGeneric Identity Provider.

   5. InSelect an authentication protocol, selectOpenID Connect (OIDC).

   6. In theCreate a provider section, do the following:

      1. InName, enter the name for the provider.
      2. InDescription, enter the description for the provider.
      3. InIssuer (URL), enter the issuer URI. The OIDC issuer URI must be in a valid URI format and start withhttps; for example,https://example.com/oidc.
      4. InClient ID, enter the OIDC client ID that is registeredwith your OIDC IdP; the ID must match theaud claim of the JWT that isissued by your IdP.

      5. To create a provider that is enabled, make sureEnable provider ison.

      6. ClickContinue.

   7. In theShare your provider information with IdP section, copy the URL.In your IdP, configure this URL as the redirect URI, which informs your IdPwhere to send the assertion token after logging in.

   8. ClickContinue.

   9. In theConfigure OIDC Web Sign-in section, do the following:

      1. In theFlow type list, selectCode.

      2. In theAssertion claims behavior list, select either of the following:

         • User info and ID token
         • Only ID token

      3. In theClient secret field, enter the client secret from your IdP.

      4. Optional: If you selectedOkta as your IdP, add any extra OIDC scopes in theAdditional scopes beyond openid, profile, and email field.

   10. ClickContinue.

   11. InConfigure provider, you can configure an attribute mappingand an attribute condition. To create anattribute mapping,do the following. You can provide either the IdP field name or aCEL-formattedexpression that returns a string.

       1. Required: InOIDC 1, enter the subject from the IdP— for example,assertion.sub.

       2. Optional: To add additional attribute mappings, do the following:

          1. ClickAdd mapping.
          2. InGooglen, wheren is a number, enter one oftheGoogle Cloud-supported keys.
          3. In the correspondingOIDCn field, enter the name of theIdP-specific field to map, in CEL format.

       3. If you selectedMicrosoft Entra ID as your IdP, you can increase the number of groups.

          1. SelectUse Extra Attributes.
          2. In theExtra Attributes Issuer URI field, enter the issuer URL.
          3. In theExtra Attributes Client ID field, enter the client ID.
          4. In theExtra Attributes Client Secret field, enter the client secret.
          5. In theExtra Attributes Type list, select an attribute type for extra attributes.
          6. In theExtra Attributes Filter field, enter a filter expression that is used when querying the Microsoft Graph API for groups.

       4. To create an attribute condition, do the following:

          Warning: If your multi-tenant IdP has a single issuer URI, you must useattribute conditions to ensure that access is restricted to the correct tenant. For more information, seeUse attribute conditions when federating with GitHub or other multi-tenant identity providers.

          1. ClickAdd condition.
          2. In theAttribute Conditions field, enter a condition inCEL format;for example,assertion.role == 'gcp-users'. This example condition ensures that only users with the rolegcp-users can sign in using this provider.

       5. To turn on detailed audit logging, inDetailed logging, click theEnable attribute value audit logging toggle.

          Workforce Identity Federationdetailed audit logging logs information received from your IdP to Logging. Detailed audit logging can help you troubleshoot your workforce identity pool provider configuration. To learn how to troubleshoot attribute mapping errors with detailed audit logging, seeGeneral attribute mapping errors. To learn about Logging pricing, seeGoogle Cloud Observability pricing.

          To disable detailed audit logging for a workforce identity pool provider, omit the--detailed-audit-logging flag when you rungcloud iam workforce-pools providers create. To disable detailed audit logging, you can alsoupdate the provider.

   12. To create the provider, clickSubmit.

   Implicit flow

   In the Google Cloud console, to create an OIDC provider thatusesimplicit flow,do the following:

   1. In the Google Cloud console, go to theWorkforce Identity Pools page:

      Go to Workforce Identity Pools

   2. In theWorkforce Identity Pools table, select the pool for whichyou want to create the provider.

   3. In theProviders section,clickadd Add Provider.

   4. In theSelect a Provider vendor list, select your IdP.

      If your IdP isn't listed, then selectGeneric Identity Provider.

   5. InSelect an authentication protocol, selectOpenID Connect (OIDC).

   6. In theCreate a provider section, do the following:

      1. InName, enter the name for the provider.
      2. InDescription, enter the description for the provider.
      3. InIssuer (URL), enter the issuer URI. The OIDC issuer URI must be in a valid URI format and start withhttps; for example,https://example.com/oidc.
      4. InClient ID, enter the OIDC client ID that is registeredwith your OIDC IdP; the ID must match theaud claim of the JWT that isissued by your IdP.
      5. To create a provider that is enabled, make sureEnable provider is on.
      6. ClickContinue.

   7. In theShare your provider information with IdP section, copy the URL.In your IdP, configure this url as the redirect URI, which informs your IdPwhere to send the assertion token after logging in.

   8. ClickContinue.

   9. In theConfigure OIDC Web Sign-in section, do the following:

      1. In theFlow type list, selectID Token.

      2. In theAssertion claims behavior list,ID token is selected.

      3. Optional: If you selectedOkta as your IdP, add any extra OIDC scopes in theAdditional scopes beyond openid, profile, and email field.

   10. ClickContinue.

   11. InConfigure provider, you can configure an attribute mappingand an attribute condition. To create anattribute mapping,do the following. You can provide either the IdP field name or aCEL-formattedexpression that returns a string.

       1. Required: InOIDC 1, enter the subject from the IdP; for example,assertion.sub.

       2. Optional: To add additional attribute mappings, do the following:

          1. ClickAdd mapping.
          2. InGooglen, wheren is a number, enter one oftheGoogle Cloud-supported keys.
          3. In the correspondingOIDCn field, enter the name of theIdP-specific field to map, in CEL format.

       3. If you selectedMicrosoft Entra ID as your IdP, you can increase the number of groups.

          1. SelectUse Extra Attributes.
          2. In theExtra Attributes Issuer URI field, enter the issuer URL.
          3. In theExtra Attributes Client ID field, enter the client ID.
          4. In theExtra Attributes Client Secret field, enter the client secret.
          5. In theExtra Attributes Type list, select an attribute type for extra attributes.
          6. In theExtra Attributes Filter field, enter a filter expression that is used when querying the Microsoft Graph API for groups.

       4. To create an attribute condition, do the following:

          Warning: If your multi-tenant IdP has a single issuer URI, you must useattribute conditions to ensure that access is restricted to the correct tenant. For more information, seeUse attribute conditions when federating with GitHub or other multi-tenant identity providers.

          1. ClickAdd condition.
          2. In theAttribute Conditions field, enter a condition inCEL format;for example,assertion.role == 'gcp-users'. This example condition ensures that only users with the rolegcp-users can sign in using this provider.

       5. To turn on detailed audit logging, inDetailed logging, click theEnable attribute value audit logging toggle.

          Workforce Identity Federationdetailed audit logging logs information received from your IdP to Logging. Detailed audit logging can help you troubleshoot your workforce identity pool provider configuration. To learn how to troubleshoot attribute mapping errors with detailed audit logging, seeGeneral attribute mapping errors. To learn about Logging pricing, seeGoogle Cloud Observability pricing.

          To disable detailed audit logging for a workforce identity pool provider, omit the--detailed-audit-logging flag when you rungcloud iam workforce-pools providers create. To disable detailed audit logging, you can alsoupdate the provider.

   12. To create the provider, clickSubmit.

Create a SAML workforce pool provider

1. In your SAML IdP, register a new application for Google CloudWorkforce Identity Federation.

2. Set the audience for SAML assertions.It is usually theSP Entity ID field in your IdP configuration. You mustset it to the following URL:

   https://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID

3. Set the redirect URL, also known as the Assertion Consumer Service(ACS) URL. To set the redirect URL, locate the redirect URL field in yourSAML IdP, and do one of the following:

   • To set up browser-based sign-in through the Google Cloud console oranother browser-based sign-in method, enter following URL:

     https://auth.cloud.google/signin-callback/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID

     Replace the following:

     • WORKFORCE_POOL_ID: the workforce identity pool ID

     • WORKFORCE_PROVIDER_ID: the ID of the workforceidentity pool provider that you create later in this document.

   • To set up programmatic sign-in through your IdP, enter the following URL:

     localhost

   SeeSet up user access to the consolefor more details on configuring console sign-in.

4. In Google Cloud, create a SAML workforce identity pool providerusing your IdP's SAML metadata document. You can download the SAML metadataXML document from your IdP. The document must include at least thefollowing:

   • A SAML entity ID for your IdP.
   • The single-sign-on URL for your IdP.
   • At least one signing public key. SeeKey requirementslater in this guide for details on signing keys.

gcloudiamworkforce-poolsproviderscreate-samlWORKFORCE_PROVIDER_ID\--workforce-pool=WORKFORCE_POOL_ID\--display-name="DISPLAY_NAME"\--description="DESCRIPTION"\--idp-metadata-path=METADATA_FILE_PATH\--attribute-mapping="ATTRIBUTE_MAPPING"\--attribute-condition="ATTRIBUTE_CONDITION"\--location=global

gcloudiamworkforce-poolsproviderskeyscreateKEY_ID\--workforce-poolWORKFORCE_POOL_ID\--providerWORKFORCE_PROVIDER_ID\--locationglobal\--useencryption\--specKEY_SPECIFICATION

gcloudiamworkforce-poolsproviderskeysdescribeKEY_ID\--workforce-poolWORKFORCE_POOL_ID\--providerWORKFORCE_PROVIDER_ID\--locationglobal\--format"value(keyData.key)"\>CERTIFICATE_PATH

gcloudiamworkforce-poolsproviderskeysdeleteKEY_ID\--workforce-poolWORKFORCE_POOL_ID\--providerWORKFORCE_PROVIDER_ID\--locationglobal

Workforce principal identifiers for IAM policies

The following table shows the principal identifiers that you can use to grant rolesto individual users and groups of users.

For a complete list of principal identifiers, seePrincipal identifiers.

Grant IAM roles to principals

You can grant roles to principals, such as single identities, groups ofidentities, or an entire pool.

To grant a role on a project to a principal, execute the following command:

gcloudprojectsadd-iam-policy-bindingPROJECT_ID\--role="ROLE"\--member="PRINCIPAL"

Replace the following:

• PROJECT_ID: the project ID
• ROLE: the role to grant
• PRINCIPAL: the principal; seePrincipal identifiers for Workforce Identity Federation.

In the example that follows, the command grants the Storage Admin role(roles/storage.admin) to all identities within the groupGROUP_ID:

gcloudprojectsadd-iam-policy-bindingmy-project\--role="roles/storage.admin"\--member="principalSet://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/group/GROUP_ID"

For more information about the principal format, seePrincipal identifiersfor Workforce Identity Federation.

Delete users

Workforce Identity Federation creates user metadata and resources forfederated user identities. If you choose to delete users in your IdP you mustalso explicitly delete these resources in Google Cloud.To do so, seeDelete Workforce Identity Federation users and their data.

You might see resources continue to be associated with a user that was deleted.This is because deleting user metadata and resources requires a long-runningoperation. After you initiate a deletion of a user's identity, processes thatthe user initiated before the deletion can continue to run until the processescomplete or are canceled.

Configure SCIM

This section describes how to configure a SCIM tenant in a workforce identity pool. To learn more about SCIM, seeSCIM provisioning for Workforce Identity Federation.

Each workforce identity pool supports only one SCIM tenant. To configure a new SCIM tenant in a pool that already has one, you must firsthard-delete the existing tenant.

The--claim-mapping flag for a SCIM tenant can contain only specific Common Expression Language (CEL) expressions. To learn which expressions are supported, seeMap token and SCIM attributes.

Important: Make sure that your IdP provides unique values for the attributes that you map togoogle.subject andgoogle.group using SCIM. To learn more, seeSCIM support.

• Configure a SCIM tenant and token in Google Cloud
• Configure SCIM in your IdP

Configure a SCIM tenant and token in Google Cloud

To configure a SCIM tenant in Google Cloud, do the following:

1. Create a SCIM tenant.

       gcloud iam workforce-pools providers scim-tenants createSCIM_TENANT_ID \        --workforce-pool="WORKFORCE_POOL_ID" \        --provider="PROVIDER_ID" \        --display-name="SCIM_TENANT_DISPLAY_NAME" \        --description="SCIM_TENANT_DESCRIPTION" \        --claim-mapping="CLAIM_MAPPING" \        --location="global"

   Replace the following:

   • SCIM_TENANT_ID: an ID for your SCIM tenant.
   • WORKFORCE_POOL_ID: the ID of the workforce pool that you created earlier in this document.
   • PROVIDER_ID: the ID of the workforce identity pool provider that you created earlier in this document.
   • SCIM_TENANT_DISPLAY_NAME: a display name for your SCIM tenant.
   • SCIM_TENANT_DESCRIPTION: a description for your SCIM tenant.
   • CLAIM_MAPPING: a comma-separated list of attribute mappings. For the extended list of mapping attributes, seeMap token and SCIM attributes. The following mapping is recommended for Gemini Enterprise:

     google.subject=user.emails[0].value.lowerAscii(),google.group=group.externalId

     Thegoogle.subject attribute that you map in the SCIM tenant must uniquely refer to the same identities that are mapped in thegoogle.subject attribute in the workforce identity pool provider by using the--attribute-mapping flag. After the SCIM tenant is created, you can't update the claim mapping. To replace it, you canhard-delete the SCIM tenant and immediately create a new one. To learn more about considerations for using SCIM, seeSCIM support.

2. When the command completes, do the following:

   1. In thebaseUri field in the output, save the entire URI, which is formatted ashttps://iamscim.googleapis.com/v1alpha1/tenants/SCIM_TENANT_UID. You need to provide this URI to your IdP.
   2. Additionally, from the URI, save only theSCIM_TENANT_UID. You need this UID to set IAM policies on the SCIM tenant, later in this document.

3. Create a SCIM token:

       gcloud iam workforce-pools providers scim-tenants tokens createSCIM_TOKEN_ID \        --display-nameDISPLAY_NAME \        --scim-tenantSCIM_TENANT_ID \        --workforce-poolWORKFORCE_POOL_ID \        --providerPROVIDER_ID \        --location global

   Replace the following:

   • SCIM_TOKEN_ID: an ID for the SCIM token
   • DISPLAY_NAME: the display name of the SCIM token
   • WORKFORCE_POOL_ID: the ID of the workforce pool
   • SCIM_TENANT_ID: the ID of the SCIM tenant
   • PROVIDER_ID: the ID of the workforce identity pool provider

4. When thegcloud iam workforce-pools providers scim-tenants tokens create command completes, do the following:

   1. In the output, save the value ofSCIM_TOKEN in thesecurityToken field. You need to provide this security token to your IdP. The security token is displayed only in this output, and if it's lost, you must create a new SCIM token.
   2. To check ifSCIM_TOKEN is rejected by your organization policy, run the following command:

      curl -v -H "Authorization: BearerSCIM_TOKEN"  https://iamscim.googleapis.com/v1alpha1/tenants/SCIM_TENANT_UID/Users

      If the command fails with a permissions-related error, rungcloud organizations add-iam-policy-binding, described in a later step. If the command succeeds, you can skip that step.

5. Set IAM policies on the SCIM tenant and token. If thecurl command in a previous step failed with a permissions-related error, you must run the following command:

       gcloud organizations add-iam-policy-bindingORGANIZATION_ID \        --member=serviceAccount:SERVICE_AGENT_EMAIL \        --role roles/iam.scimSyncer

   Replace the following:

   • ORGANIZATION_ID: the ID of the organization.
   • SERVICE_AGENT_EMAIL: the email address of the service agent. The email address is in the following format:o-ORGANIZATION_ID-SCIM_TENANT_UID@gcp-sa-iamscim.iam.gserviceaccount.com.SCIM_TENANT_UID is returned when you create the SCIM tenant.

When you provision groups in your IdP, make sure that each group's display name, as provided in thedisplayName field, is unique within a SCIM tenant. To learn more about groups and SCIM in Microsoft Entra ID, seeGroups.

Configure SCIM in your OIDC or SAML IdP

In your IdP, configure SCIM as described in your IdP documentation. Use the SCIM URL and SCIM token obtained in the previous step.

Update the provider to enable SCIM

To enable SCIM for a provider, do the following:

      gcloud iam workforce-pools providers update-oidcPROVIDER_ID \          --workforce-pool=WORKFORCE_POOL_ID \          --location=LOCATION \          --scim-usage=enabled-for-groups

      gcloud iam workforce-pools providers update-samlPROVIDER_ID \          --workforce-pool=WORKFORCE_POOL_ID \          --location=LOCATION \          --scim-usage=enabled-for-groups

Map token and SCIM attributes

You must consistently map attributes, both in the workforce identity pool provider and in the SCIM tenant that's configured for the provider. For the workforce identity pool provider, you use the--attribute-mapping flag, and for the SCIM tenant, you use the--claim-mapping flag. The IdP attribute that is mapped togoogle.subject for users must uniquely refer to the same identity, whether defined in a token or SCIM mapping. To learn more about mapping attributes when you use SCIM, see theSCIM support section.The following table shows you how to map attributes in token claims and SCIM attributes:

Force delete a SCIM tenant

To force delete a SCIM tenant, do the following:

1. If--scim-usage=enabled-for-groups is set for your provider, disable it from the provider configuration:

             gcloud iam workforce-pools providers update-oidc          --provider=PROVIDER_ID \          --workforce-pool=WORKFORCE_POOL_ID \          --location= global          --scim-usage=SCIM_USAGE_UNSPECIFIED

   Replace the following:

   • PROVIDER_ID: the ID of the workforce identity pool provider
   • WORKFORCE_POOL_ID: the ID of the workforce pool

2. Delete the SCIM tenant:

     gcloud iam workforce-pools providers scim-tenants deleteSCIM_TENANT_ID \      --workforce-pool=WORKFORCE_POOL_ID \      --provider=PROVIDER_ID \      --hard-delete \      --location=global

   Replace the following:

   • SCIM_TENANT_ID: the ID of the SCIM tenant to delete
   • WORKFORCE_POOL_ID: the ID of the workforce pool
   • PROVIDER_ID: the ID of the workforce identity pool provider
   To learn more about SCIM, including deleting SCIM tenants, seeSCIM support.

What's next

• Obtain short-lived credentials for Workforce Identity Federation
• Manage workforce identity pool providers
• Delete Workforce Identity Federation users and their data
• Learn which Google Cloud productssupport Workforce Identity Federation
• Set up user access to console (federated)