This document shows you how to configure Workforce Identity Federation withthe Microsoft Entra ID identity provider (IdP) and manage access toGoogle Cloud. Federated users can then access Google Cloud servicesthatsupport Workforce Identity Federation.You can use either the OIDC protocol or SAML 2.0 protocol to federateidentities.

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. In Microsoft Entra ID, make sure that ID tokens are enabled for implicit flow. For more information, seeEnable ID token implicit grant.
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 theIAM Workforce 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.

If you're configuring permissions in a development or test environment—but not aproduction environment—you can grant the IAM Owner(roles/owner) basic role, which also includes permissions forWorkforce Identity Federation.

Create a Microsoft Entra ID application

Workforce identity pools support federation using both OIDC and SAML protocols.

Create a workforce identity pool

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

Create the Microsoft Entra ID 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 identity pool provider

To create a workforce identity pool provider for your Microsoft Entra IDapplication integration, using the OIDC protocol, do the following:

1. To get the issuer URI for your Microsoft Entra ID application, do thefollowing:

   1. Go to your Microsoft Entra ID application registration.
   2. ClickEndpoints.
   3. Open theOpenID Connect metadata document in a new tab.
   4. In the JSON, copy the value ofissuer.

2. To get the client ID for your Microsoft Entra ID application, do thefollowing:

   1. Go to your Microsoft Entra ID application registration.
   2. InApplication (client) ID, copy the value.

3. To create an OIDC workforce identity pool provider for web-basedsign-in, do the following:

   gcloud

   To create a provider that supports the OIDC protocol, do the following:

   Code flow

   To create an OIDC provider that usesauthorization code flow for web-based sign-in,do the following:

   1. In your Microsoft Entra ID application, to get your client secret,do the following:

      1. Go to your Microsoft Entra ID app registration.

      2. InCertificates & secrets, click theClient secrets tab.

      3. To add a client secret, click+ New client secret.

      4. In theAdd a client secret dialog, enter information, as needed.

      5. To create the client secret, clickAdd.

      6. In theClient secrets tab, find your new client secret.

      7. In theValue column for your new client secret, clickcontent_copyCopy.

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

      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. For Microsoft Entra ID with OIDC authentication, we recommend the followingattribute mappings:

        google.subject=assertion.sub,google.groups=assertion.groups,google.display_name=assertion.preferred_username

        This example maps the IdP attributessubject,groups, andpreferred_username to the Google Cloudattributesgoogle.subject,google.groups,andgoogle.display_name, respectively.

      • ATTRIBUTE_CONDITION: Anattribute condition; for example, to limit theipaddr attribute to acertain IP range you can set the conditionassertion.ipaddr.startsWith('98.11.12.').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, do the following:

   1. To enable the ID token in your Microsoft Entra ID application, dothe following:

      1. Go to your Microsoft Entra ID application registration.
      2. InAuthentication, select theID token checkbox.
      3. ClickSave.

   2. To create the provider, 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. For Microsoft Entra ID with OIDC authentication, we recommend the followingattribute mappings:

        google.subject=assertion.sub,google.groups=assertion.groups,google.display_name=assertion.preferred_username

        This example maps the IdP attributessubject,groups, andpreferred_username to the Google Cloudattributesgoogle.subject,google.groups,andgoogle.display_name, respectively.

      • ATTRIBUTE_CONDITION: Anattribute condition; for example, to limit theipaddr attribute to acertain IP range you can set the conditionassertion.ipaddr.startsWith('98.11.12.').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.

   Console

   Code flow

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

   1. To get the Microsoft Entra ID client secret, do the following:

      1. Go to your Microsoft Entra ID app registration.

      2. InCertificates & secrets, click theClient secrets tab.

      3. To add a client secret, click+ New client secret.

      4. In theAdd a client secret dialog, enter information, as needed.

      5. To create the client secret, clickAdd.

      6. In theClient secrets tab, find your new client secret.

      7. In theValue column for your new client secret, clickcontent_copyCopy.

   2. 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.

             For Microsoft Entra ID with OIDC authentication, we recommend the followingattribute mappings:

             google.subject=assertion.sub,google.groups=assertion.groups,google.display_name=assertion.preferred_username

             This example maps the IdP attributessubject,groups, andpreferred_username to the Google Cloudattributesgoogle.subject,google.groups,andgoogle.display_name, respectively.

          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, to limit theipaddr attribute to acertain IP range you can set the conditionassertion.ipaddr.startsWith('98.11.12.').

          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

   To create an OIDC provider that usesimplicit flowfor web-based sign-in, do the following:

   1. To enable the ID token in your Microsoft Entra ID application, dothe following:

      1. Go to your Microsoft Entra ID application registration.
      2. InAuthentication, select theID token checkbox.
      3. ClickSave.

   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.

          For Microsoft Entra ID with OIDC authentication, we recommend the followingattribute mappings:

          google.subject=assertion.sub,google.groups=assertion.groups,google.display_name=assertion.preferred_username

          This example maps the IdP attributessubject,groups, andpreferred_username to the Google Cloudattributesgoogle.subject,google.groups,andgoogle.display_name, respectively.

       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, to limit theipaddr attribute to acertain IP range you can set the conditionassertion.ipaddr.startsWith('98.11.12.').

       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 2.0 workforce identity 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="XML_METADATA_PATH"\--attribute-mapping="ATTRIBUTE_MAPPING"\--attribute-condition="ATTRIBUTE_CONDITION"\--detailed-audit-logging\--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

Manage access to Google Cloud resources

This section provides an example that shows you how to manage access toGoogle Cloud resources by Workforce Identity Federation users.

In this example, you grant an Identity and Access Management (IAM) role on a sampleproject. Users can thensign in and use this project toaccess Google Cloud products.

You can manage IAM roles for single identities, a group ofidentities, or an entire pool. For more information, seeRepresent workforce identity pool users in IAM policies.

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

gcloudprojectsadd-iam-policy-bindingTEST_PROJECT_ID\--role="roles/storage.admin"\--member="principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/SUBJECT_VALUE"

gcloudprojectsadd-iam-policy-bindingTEST_PROJECT_ID\--role="roles/storage.admin"\--member="principalSet://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/attribute.department/DEPARTMENT_VALUE"

Sign in and test access

In this section, you sign in as a workforce identity pool user and test that youhave access to Google Cloud resources.

Sign in

This section shows you how to sign in as a federated user and accessGoogle Cloud resources.

gcloudiamworkforce-poolscreate-login-config\locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID\--output-file=LOGIN_CONFIG_FILE_PATH

{"type":"external_account_authorized_user_login_config","audience":"//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID","auth_url":"https://auth.cloud.google/authorize","token_url":"https://sts.googleapis.com/v1/oauthtoken","token_info_url":"https://sts.googleapis.com/v1/introspect"}

Test Access

You now have access to the Google Cloud products that supportWorkforce Identity Federation and to which you are granted access. Earlier inthis document, yougranted the Storage Admin role (roles/storage.admin)to all of the identities within the group identifier that you specified in thegcloud projects add-iam-policy-binding for projectTEST_PROJECT_ID.

You can now test that you have access by listing Cloud Storage buckets.

gcloudstoragels--project="TEST_PROJECT_ID"

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

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. We recommend that you use the following attribute mapping:

     google.subject=user.externalId,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 Microsoft Entra ID

To configure SCIM in Microsoft Entra ID, do the following:

1. Open the Azure portal and sign in as a user that has global administrator privileges.
2. SelectMicrosoft Entra ID>Enterprise Apps.
3. ClickNew application.
4. InBrowse Microsoft Entra App gallery, clickCreate your own application.
5. In theCreate your own application panel that appears, do the following:
   1. ForWhat's the name of your app, enter the name of your app.
   2. SelectIntegrate any other application you don't find in gallery (Non-gallery).
   3. To create the app, clickCreate.
6. In your application, do the following:
   1. In theManage section, clickProvisioning.
   2. In the right pane that appears, clickNew Configuration.

   3. Under theAdmin Credentials, in theTenant URL, enter the SCIM URL that you obtained when you created the SCIM tenant, appended with?aadOptscim062020. You must append?aadOptscim062020 to the end of the base URI.

      This query parameter is required by Microsoft Entra ID to ensure that SCIM PATCH requests are compliant with SCIM RFC standards. For more details, seeMicrosoft's documentation.

      The final Tenant URL in Microsoft Entra ID should be in the following format:

      https://iamscim.googleapis.com/v1alpha1/tenants/SCIM_TENANT_UID?aadOptscim062020

      ReplaceSCIM_TENANT_UID with the SCIM tenant UID.

   4. InSecret token, enter the secret token that you obtained when you created the SCIM tenant.
   5. To test the SCIM configuration with Workforce Identity Federation, clickTest connection.
   6. To save the configuration, clickCreate.
7. In theManage section, do the following:
   1. ClickAttribute mapping.
   2. ClickProvision Microsoft Entra ID Users.
   3. In theAttribute Mapping page, do the following:
      1. In theAttribute mappings table, find the row forexternalId and clickEdit in that row. In theEdit attributes page, do the following:
         1. InMatch objects using this attribute, selectYes.
         2. InMatching precedence, enter2.
         3. In theSource attribute drop-down list, selectobjectId.
         4. To save the attribute mapping, clickOk.
      2. In theAttribute mappings table, find the row foruserName and clickEdit in that row. In theEdit attributes page, do the following:
         1. InMatch objects using this attribute, selectNo.
         2. To save the attribute mapping, clickOk.
      3. In theAttribute mappings table, find the row forexternalId and clickEdit in that row. In theEdit attributes page, do the following:
         1. InMatching precedence, enter1.
         2. To save the attribute mapping, clickOk.
   4. ClickProvision Microsoft Entra ID Groups.
   5. In theAttribute Mapping page, do the following:
      1. In theAttribute mappings table, find the row forexternalId and clickEdit in that row. In theEdit attributes page, do the following:
         1. InMatch objects using this attribute, selectYes.
         2. InMatching precedence, enter2.
         3. In theSource attribute drop-down list, selectobjectId.
         4. To save the attribute mapping, clickOk.
      2. In theAttribute mappings table, find the row fordisplayName and clickEdit in that row. In theEdit attributes page, do the following:
         1. InMatch objects using this attribute, selectNo.
         2. To save the attribute mapping, clickOk.
      3. In theAttribute mappings table, find the row forexternalId and clickEdit in that row. In theEdit attributes page, do the following:
         1. InMatching precedence, enter1.
         2. To save the attribute mapping, clickOk.

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 is configure for the provider. For the workforce identity pool provider, you use the--attribute-mapping flag, and for the SCIM tenant, you use the 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

• Delete Workforce Identity Federation users and their data
• Learn which Google Cloud productssupport Workforce Identity Federation
• Set up user access to console (federated)