Configure Workforce Identity Federation with Microsoft Entra ID

You can configure Workforce Identity Federation with the Microsoft Entra IDidentity provider (IdP) and map up to 400 groups fromMicrosoft Entra ID to Google Cloud by using Microsoft Graph. You can thengrant IAM roles to those groups, which allows MicrosoftEntra ID users that are members of the groups to sign into Google Cloud. Theusers can then access Google Cloud products to which they were granted IAM access that alsosupport Workforce Identity Federation.

To map fewer than 150 groups from Microsoft Entra ID to Google Cloud, seeConfigure Workforce Identity Federation with Microsoft Entra ID and sign in users.

Key concepts

This section describes concepts that are used to configure Workforce Identity Federation, later in this document.

Extra attributes

To map up to 400 group, you useextra attributes byspecifyingextra-attributes flags when you create the workforce identitypool provider. You can use extra attributes with the following protocols:

  • OIDC with implicit flow
  • OIDC with code flow
  • SAML 2.0 protocol

The number of group email addresses that a Microsoft Entra ID application canemit in a token is limited to 150 for SAML and 200 for JWT. To learn more aboutthis limit, seeConfigure group claims for applications by using Microsoft Entra ID.To retrieve more groups, Workforce Identity Federation uses MicrosoftIdentity'sOAuth 2.0 client credentials flowto obtain credentials that allow Workforce Identity Federationto query Microsoft Graph API and fetch a user's groups.

To use extra attributes, at a high level, you do the following:

  • Create a new Microsoft Entra ID application or update your existingapplication to obtain users' group memberships from the Microsoft Graph API.To learn more about how Microsoft Graph retrieves a large number of groupsfrom Microsoft Entra ID, seeGroup overages.

  • When you create the workforce identity pool provider, you useextra-attributes flags to configure Workforce Identity Federation toretrieve users' group email addresses from the Microsoft Graph API.

Workforce Identity Federation can retrieve a maximum of 999 groups from theMicrosoft Graph API. If the Microsoft Graph API returns more than 999 groups,the sign-in fails.

To reduce the number of groups that the Microsoft Graph API returns, you canrefine Workforce Identity Federation's query by using the--extra-attributes-filter flag, when you create the workforce identity poolprovider.

After Workforce Identity Federation retrieves the groups from the MicrosoftGraph API, it mints the access token. Workforce Identity Federation can add amaximum of 400 groups to the access token, so, to further filter the number ofgroups to 400 or fewer, you can specify anattribute mappingthat contains common expression language (CEL) expressions, when you create theworkforce identity pool provider.

Extended attributes

Important: SCIM is available only for Gemini Enterprise.

For Gemini Enterprise users, you can useextended attributes to mapup to 1000 groups from Microsoft Entra ID. This limit ishigher than the limit for extra attributes. To use extended attributes, youspecify theextended-attributes flags when you create theworkforce identity pool provider. By using extended attributes,Workforce Identity Federation retrieves group IDs (UUIDs) from MicrosoftEntra ID.

To let Gemini Enterprise users enter human-readable group names,instead of UUIDs, in the Gemini Enterprisenotebook sharing UI,you must also configureSCIM.

Youconfigure SCIM in Workforce Identity Federation andyour IdP as described later in this document.

You configure extended attributes by using the following flags:

  • --extended-attributes-issuer-uri
  • --extended-attributes-client-id
  • --extended-attributes-client-secret-value

When you use extended attributes, the following limitations also apply:

  • You don't need to configuregoogle.groups in the attributemapping because groups attributes aren't used. However, other attributemappings are used.

  • You can configure other workforce identity pool provider flags asdocumented, but those settings apply to products other thanGemini Enterprise that support Workforce Identity Federation.

  • Extended attributes are updated and refreshed periodically in the backgroundfor the session duration, even after sign-in.

  • In Microsoft Entra ID, you must grant the application permissionUser.Read.All instead ofUser.Read,User.ReadBasic.All, orGroupMember.Read.All.

  • The extended attributes type flag--extended-attributes-type supports only theazure-ad-groups-id type.

  • Extended attributes support only up to 1000 groups. Incontrast, the--extra-attributes flag supports up to400 groups.

  • Extended attributes can only be used for web sign-in throughvertexaisearch.cloud.google, not for console sign-ins and not forgcloud CLI sign-ins.

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.
  6. All groups that you intend to map must be marked as security groups inMicrosoft Entra ID.Important: A maximum of 999 groups can be fetched.

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

This section shows you how to create a Microsoft Entra ID application using theMicrosoft Entra admin portal. Alternatively, you can update your existingapplication. For additional details, seeEstablish applications in the Microsoft Entra ID ecosystem.

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

OIDC

To create a Microsoft Entra ID application registration that uses the OIDCprotocol, do the following:

  1. Sign in to the Microsoft Entra administrator portal.

  2. Go toIdentity>Applications>App registrations.

  3. To begin configuring the application registration, do the following:

    1. ClickNew registration.

    2. Enter a name for your application.

    3. InSupported account types, select an option.

    4. In theRedirect URI section, in theSelect a platformdrop-down list, selectWeb.

    5. In the text field, enter a redirectURL. Your users are redirected to this URL after they successfullysign in. If you are configuring access to theconsole (federated),use the following URL format:

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

      Replace the following:

      • WORKFORCE_POOL_ID: a workforce identitypool ID that you will use when creating the workforce identitypool later in this document—for example:entra-id-oidc-pool

      • WORKFORCE_PROVIDER_ID: a workforceidentity pool provider ID that you will use when you create theworkforce identity pool provider later in this document—forexample:entra-id-oidc-pool-provider

        For information on formatting the ID, seetheQuery parameterssection in the API documentation.

    6. To create the application registration, clickRegister.

    7. To use the example attribute mapping that isprovided later in this document, you must create a customdepartment attribute.

SAML

To create a Microsoft Entra ID application registration that uses the SAMLprotocol, do the following:

  1. Sign in to the Microsoft Entra administrator portal.

  2. In the left-hand navigation menu, go toEntra ID> Enterprise Apps.

  3. To begin configuring the enterprise application, do the following:

    1. ClickNew application>Create your own application.

    2. In theCreate your own application pane that appears, enter a namefor your application.

    3. ClickCreate.

    4. Go toSingle sign-on>SAML.

    5. Update theBasic SAML Configuration as follows:

      1. In theIdentifier (Entity ID) field, enter the followingvalue:

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

        Replace the following:

        • WORKFORCE_POOL_ID: a workforceidentity pool ID that you will use when creating the workforceidentity pool later in this document—for example:entra-id-saml-pool

        • WORKFORCE_PROVIDER_ID: a workforceidentity pool provider ID that you will use when you createthe workforce identity pool provider later in thisdocument—for example:entra-id-saml-pool-provider

          For information on formatting the ID, seetheQuery parameterssection in the API documentation.

      2. In theReply URL (Assertion Consumer Service URL) field, entera redirect URL. Your users are redirected to this URL after theysuccessfully sign in. If you are configuring access to theconsole (federated),use the following URL format:

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

        Replace the following:

        • WORKFORCE_POOL_ID: the workforceidentity pool ID
        • WORKFORCE_PROVIDER_ID: the workforceidentity provider ID

      3. To enable IdP-initiated sign-on, set theRelay State field tothe following value:

        https://console.cloud.google/

      4. To save the SAML application configuration, clickSave.

    6. To use the example attribute mapping that isprovided later in this document, you must create a customdepartment attribute.

Configure large numbers of groups with Microsoft Entra ID

This section describes how to map up to 400 groups fromMicrosoft Entra ID to Workforce Identity Federation using the OIDC and SAMLprotocols.

Configure large numbers of groups with Microsoft Entra ID with OIDC implicit flow

This section describes how to map up to 400 groups fromMicrosoft Entra ID to Workforce Identity Federation using the OpenID Connect(OIDC) protocol with implicit flow.

Configure your Microsoft Entra ID application

You can configure an existing Microsoft Entra ID application or create a new one. To configure your application, do the following:

  1. In the Microsoft Entra ID portal, do the following:
    • To register a new application, follow the instructions inRegister a new application.
    • To update an existing application, do the following:
      • Go toIdentity>Applications>Enterprise applications.
      • Select the application that you want to update.
  2. Create a new client secret in the application by following the instructions inCertificates & secrets. Make sure that you record the client secret value because it's displayed only once.

    Note the following values from the application that you created or updated. You provide the values when you configure the workforce identity pool provider later in this document.

    • Client ID
    • Issuer URI
    • Client Secret
    • Tenant ID

  3. To retrieve the Microsoft Entra ID groups, add the API permission to let Workforce Identity Federation access users' information from Microsoft Entra ID using the Microsoft Graph API and grant admin consent. In Microsoft Entra ID, do the following:

    1. Go toAPI permissions.
    2. ClickAdd a Permission.
    3. SelectMicrosoft API.
    4. SelectApplication permissions.
    5. In the search field, typeUser.ReadBasic.All.
    6. ClickAdd permissions.

    You can retrieve the Microsoft Entra ID groups as group object identifiers (ID) or as group email address for email enabled groups.

    If you choose to retrieve groups as group email addresses, the next step is required.

  4. To retrieve the Microsoft Entra ID groups as group email addresses, do the following. If you retrieve groups as group object identifiers, skip this step.
    1. In the search field, enterGroupMember.Read.All.
    2. ClickAdd permissions.
    3. ClickGrant admin consent for your domain name.
    4. In the dialog that appears, clickYes.
    5. Go to theOverview page of the Microsoft Entra ID application that you created or updated earlier.
    6. ClickEndpoints.

    The issuer URI is the OIDC metadata document URI, omitting the path/.well-known/openid-configuration.

    For example, if the OIDC metadata document ishttps://login.microsoftonline.com/d41ad248-019e-49e5-b3de-4bdfe1fapple/v2.0/.well-known/openid-configuration, the issuer URI ishttps://login.microsoftonline.com/d41ad248-019e-49e5-b3de-4bdfe1fapple/v2.0/.

Create a workforce identity pool

gcloud

To create the workforce identity pool, run the following command:

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

Replace the following:

  • WORKFORCE_POOL_ID: an ID that you choose to representyour Google Cloud workforce pool. For information on formatting the ID,see theQuery parameterssection in the API documentation.
  • ORGANIZATION_ID: the numeric organization ID ofyour Google Cloud organization for the workforce identity pool.Workforce identity pools are available across all projects andfolders in the organization.
  • DISPLAY_NAME: Optional. A display name for yourworkforce identity pool.
  • DESCRIPTION: Optional. A workforce identity pooldescription.
  • SESSION_DURATION: Optional. The session duration,expressed as a number appended withs—for example,3600s. Sessionduration determines how long the Google Cloud access tokens,console (federated)sign-in sessions, and gcloud CLI sign-in sessions from thisworkforce pool are valid. Session duration defaults to one hour (3600s). Thesession duration value must be between 15 minutes (900s) and 12 hours(43200s).
Tip: Rungcloud iam workforce-pools create --help to find otherparameters you can customize for this command.

Console

To create the workforce identity pool, do the following:

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

    Go to Workforce Identity Pools

  2. Select the organization for your workforce identity pool. Workforceidentity pools are available across all projects and folders in anorganization.

  3. ClickCreate pool and do the following:

    1. In theName field, enter the display name of the pool. The pool IDis automatically derived from the name as you type, and it isdisplayed under theName field. You can update the pool ID byclickingEdit next to the pool ID.

    2. Optional: InDescription, enter a description of the pool.

    3. To create the workforce identity pool, clickNext.

The workforce identity pool's session duration defaults to one hour (3600s).The session duration determines how long the Google Cloud access tokens,console (federated),and gcloud CLI sign-in sessions from this workforce poolare valid. After you create the pool, you canupdate the pool to seta custom session duration. The session duration must be from 15minutes (900s) to 12 hours (43200s).

Configure the OIDC implicit flow workforce identity pool provider

gcloud

To create the OIDC workforce identity pool provider, run the following command:

gcloud iam workforce-pools providers create-oidcPROVIDER_ID \    --workforce-pool=WORKFORCE_POOL_ID \    --location=global \    --display-name=DISPLAY_NAME \    --issuer-uri=ISSUER_URI \    --client-id=CLIENT_ID \    --attribute-mapping=ATTRIBUTE_MAPPING \    --web-sso-response-type=id-token \    --web-sso-assertion-claims-behavior=only-id-token-claims \    --extra-attributes-issuer-uri=EXTRA_ATTRIBUTES_ISSUER_URI \    --extra-attributes-client-id=EXTRA_ATTRIBUTES_CLIENT_ID \    --extra-attributes-client-secret-value=EXTRA_ATTRIBUTES_CLIENT_SECRET \    --extra-attributes-type=EXTRA_ATTRIBUTES_TYPE  \    --extra-attributes-filter=EXTRA_ATTRIBUTES_FILTER \    --detailed-audit-logging

Replace the following:

  • PROVIDER_ID: a unique provider ID. The prefixgcp- is reserved and can't be used in a pool or provider ID.
  • WORKFORCE_POOL_ID: the workforce pool ID.
  • DISPLAY_NAME: a display name for the provider.
  • ISSUER_URI: the issuer URI from the Microsoft Entra ID application that you created earlier in this document.
  • CLIENT_ID: the client ID from your Microsoft Entra ID application.
  • ATTRIBUTE_MAPPING: the mapping of attributes from Microsoft Entra ID to Google Cloud. For example, to mapgroups andsubject attributes from Microsoft Entra ID, use the following attribute mapping:
    --attribute-mapping="google.groups=assertion.groups, google.subject=assertion.sub"

    For more information, seeAttribute mapping.

  • EXTRA_ATTRIBUTES_ISSUER_URI: the issuer URI from your Microsoft Entra ID application.
  • EXTRA_ATTRIBUTES_CLIENT_ID: the client ID from your Microsoft Entra ID application.
  • EXTRA_ATTRIBUTES_CLIENT_SECRET: the extra client secret from your Microsoft Entra ID application.
  • EXTRA_ATTRIBUTES_TYPE: useazure-ad-groups-mail to retrieve the email addresses of the groups. Useazure-ad-groups-id to retrieve the IDs of the groups.
  • EXTRA_ATTRIBUTES_FILTER: Optional. A filter expression that is used when querying the Microsoft Graph API for groups. You can use this parameter to ensure that the number of groups fetched from the IdP remains below the limit of 400 groups.

    The following example fetches the groups that have the prefixsales in their email ID:

    --extra-attributes-filter='"mail:sales"'

    The following expression fetches groups with a display name that contains the stringsales.

    --extra-attributes-filter='"displayName:sales"'

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

Console

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

    2. Go to Workforce Identity Pools

  2. In theWorkforce Identity Pools table, select the pool forwhich you want to create the provider.
  3. In theProviders section, click.
  4. In theSelect a Provider vendor list, select your identityprovider (IdP).

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

  5. InSelect an authentication protocol, selectOpenIDConnect (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 sureEnableprovider is on.

    6. ClickContinue.
  7. In theShare your provider information with IdP section, copythe URL. In your IdP, configure this URL as the redirect URI, whichinforms your IdP where to send the assertion token after logging in.
  8. ClickContinue.
  9. In theConfigure OIDC Web Sign-in section, do thefollowing:
  10. In theFlow type list, selectID Token.
  11. In theAssertion claims behavior list,ID token isselected.
  12. Optional: If you selectedOkta as your IdP, addany extra OIDC scopes in theAdditional scopes beyond openid,profile, and email field.
  • ClickContinue.
  • InConfigure provider, you can configure an attributemapping and an attribute condition. To create anattributemapping, do the following. You can provide either the IdP fieldname or aCEL-formattedexpression that returns a string.
    1. Required: InOIDC 1, enter the subject from the IdP— forexample,assertion.sub.
    2. Optional: To add additional attribute mappings, do the following:
      1. ClickAdd mapping.
      2. InGooglen, wheren is a number, enter oneof theGoogle Cloud-supportedkeys.
      3. In the correspondingOIDCn field, enter the nameof the IdP-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 issuerURL.
      3. In theExtra Attributes Client ID field, enter the clientID.
      4. In theExtra Attributes Client Secret field, enter the clientsecret.
      5. In theExtra Attributes Type list, select an attribute typefor extra attributes.
      6. In theExtra Attributes Filter field, enter a filterexpression that is used when querying the Microsoft Graph API forgroups.
    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.
      3. 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.

  • To create the provider, clickSubmit.

    • Configure large numbers of groups in Microsoft Entra ID with OIDC code flow

    This section describes how to map up to 400 groups fromMicrosoft Entra ID to Workforce Identity Federation using the OIDC protocolwith code flow.

    Configure your Microsoft Entra ID application

    You can configure an existing Microsoft Entra ID application or create a new one. To configure your application, do the following:

    1. In the Microsoft Entra ID portal, do the following:
      • To register a new application, follow the instructions inRegister a new application.
      • To update an existing application, do the following:
        • Go toIdentity>Applications>Enterprise applications.
        • Select the application that you want to update.
    2. Create a new client secret in the application by following the instructions inCertificates & secrets. Make sure that you record the client secret value because it's displayed only once.

      Note the following values from the application that you created or updated. You provide the values when you configure the workforce identity pool provider later in this document.

      • Client ID
      • Issuer URI
      • Client Secret
      • Tenant ID

    3. To retrieve the Microsoft Entra ID groups, add the API permission to let Workforce Identity Federation access users' information from Microsoft Entra ID using the Microsoft Graph API and grant admin consent. In Microsoft Entra ID, do the following:

      1. Go toAPI permissions.
      2. ClickAdd a Permission.
      3. SelectMicrosoft API.
      4. SelectDelegated permissions.
      5. In the search field, typeUser.Read.
      6. ClickAdd permissions.

      You can retrieve the Microsoft Entra ID groups as group object identifiers (ID) or as group email address for email enabled groups.

      If you choose to retrieve groups as group email addresses, the next step is required.

    4. To retrieve the Microsoft Entra ID groups as group email addresses, do the following. If you retrieve groups as group object identifiers, skip this step.
      1. In the search field, enterGroupMember.Read.All.
      2. ClickAdd permissions.
      3. ClickGrant admin consent for your domain name.
      4. In the dialog that appears, clickYes.
      5. Go to theOverview page of the Microsoft Entra ID application that you created or updated earlier.
      6. ClickEndpoints.

      The issuer URI is the OIDC metadata document URI, omitting the path/.well-known/openid-configuration.

      For example, if the OIDC metadata document ishttps://login.microsoftonline.com/d41ad248-019e-49e5-b3de-4bdfe1fapple/v2.0/.well-known/openid-configuration, the issuer URI ishttps://login.microsoftonline.com/d41ad248-019e-49e5-b3de-4bdfe1fapple/v2.0/.

    Create a workforce identity pool

    gcloud

    To create the workforce identity pool, run the following command:

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

    Replace the following:

    • WORKFORCE_POOL_ID: an ID that you choose to representyour Google Cloud workforce pool. For information on formatting the ID,see theQuery parameterssection in the API documentation.
    • ORGANIZATION_ID: the numeric organization ID ofyour Google Cloud organization for the workforce identity pool.Workforce identity pools are available across all projects andfolders in the organization.
    • DISPLAY_NAME: Optional. A display name for yourworkforce identity pool.
    • DESCRIPTION: Optional. A workforce identity pooldescription.
    • SESSION_DURATION: Optional. The session duration,expressed as a number appended withs—for example,3600s. Sessionduration determines how long the Google Cloud access tokens,console (federated)sign-in sessions, and gcloud CLI sign-in sessions from thisworkforce pool are valid. Session duration defaults to one hour (3600s). Thesession duration value must be between 15 minutes (900s) and 12 hours(43200s).
    Tip: Rungcloud iam workforce-pools create --help to find otherparameters you can customize for this command.

    Console

    To create the workforce identity pool, do the following:

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

      Go to Workforce Identity Pools

    2. Select the organization for your workforce identity pool. Workforceidentity pools are available across all projects and folders in anorganization.

    3. ClickCreate pool and do the following:

      1. In theName field, enter the display name of the pool. The pool IDis automatically derived from the name as you type, and it isdisplayed under theName field. You can update the pool ID byclickingEdit next to the pool ID.

      2. Optional: InDescription, enter a description of the pool.

      3. To create the workforce identity pool, clickNext.

    The workforce identity pool's session duration defaults to one hour (3600s).The session duration determines how long the Google Cloud access tokens,console (federated),and gcloud CLI sign-in sessions from this workforce poolare valid. After you create the pool, you canupdate the pool to seta custom session duration. The session duration must be from 15minutes (900s) to 12 hours (43200s).

    Configure the OIDC code flow workforce identity pool provider

    gcloud

    To create the OIDC workforce identity pool provider, run the following command:

    gcloud iam workforce-pools providers create-oidcPROVIDER_ID \    --workforce-pool=WORKFORCE_POOL_ID \    --location=global \    --display-name=DISPLAY_NAME \    --issuer-uri=ISSUER_URI \    --client-id=CLIENT_ID \
        --client-secret-value="OIDC_CLIENT_SECRET" \    --attribute-mapping=ATTRIBUTE_MAPPING \    --web-sso-response-type=code \    --web-sso-assertion-claims-behavior=merge-user-info-over-id-token-claims \    --extra-attributes-issuer-uri=EXTRA_ATTRIBUTES_ISSUER_URI \    --extra-attributes-client-id=EXTRA_ATTRIBUTES_CLIENT_ID \    --extra-attributes-client-secret-value=EXTRA_ATTRIBUTES_CLIENT_SECRET \    --extra-attributes-type=EXTRA_ATTRIBUTES_TYPE  \    --extra-attributes-filter=EXTRA_ATTRIBUTES_FILTER \    --detailed-audit-logging

    Replace the following:

    • PROVIDER_ID: a unique provider ID. The prefixgcp- is reserved and can't be used in a pool or provider ID.
    • WORKFORCE_POOL_ID: the workforce pool ID.
    • DISPLAY_NAME: a display name for the provider.
    • ISSUER_URI: the issuer URI from the Microsoft Entra ID application that you created earlier in this document.
    • CLIENT_ID: the client ID from your Microsoft Entra ID application.
    • ATTRIBUTE_MAPPING: the mapping of attributes from Microsoft Entra ID to Google Cloud. For example, to mapgroups andsubject attributes from Microsoft Entra ID, use the following attribute mapping:
      --attribute-mapping="google.groups=assertion.groups, google.subject=assertion.sub"

      For more information, seeAttribute mapping.

    • EXTRA_ATTRIBUTES_ISSUER_URI: the issuer URI from your Microsoft Entra ID application.
    • EXTRA_ATTRIBUTES_CLIENT_ID: the client ID from your Microsoft Entra ID application.
    • EXTRA_ATTRIBUTES_CLIENT_SECRET: the extra client secret from your Microsoft Entra ID application.
    • EXTRA_ATTRIBUTES_TYPE: useazure-ad-groups-mail to retrieve the email addresses of the groups. Useazure-ad-groups-id to retrieve the IDs of the groups.
    • EXTRA_ATTRIBUTES_FILTER: Optional. A filter expression that is used when querying the Microsoft Graph API for groups. You can use this parameter to ensure that the number of groups fetched from the IdP remains below the limit of 400 groups.

      The following example fetches the groups that have the prefixsales in their email ID:

      --extra-attributes-filter='"mail:sales"'

      The following expression fetches groups with a display name that contains the stringsales.

      --extra-attributes-filter='"displayName:sales"'

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

    Console

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

      2. Go to Workforce Identity Pools

    2. In theWorkforce Identity Pools table, select the pool forwhich you want to create the provider.
    3. In theProviders section, click.
    4. In theSelect a Provider vendor list, select your identityprovider (IdP).

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

    5. InSelect an authentication protocol, selectOpenIDConnect (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 sureEnableprovider is on.

      6. ClickContinue.
    7. In theShare your provider information with IdP section, copythe URL. In your IdP, configure this URL as the redirect URI, whichinforms your IdP where to send the assertion token after logging in.
    8. ClickContinue.
    9. In theConfigure OIDC Web Sign-in section, do thefollowing:
      1. In theFlow type list, selectCode.
      2. In theAssertion claims behavior list, select either of thefollowing:
        • User info and ID token
        • Only ID token
      3. In theClient secret field, enter the client secret fromyour IdP.
      4. Optional: If you selectedOkta as your IdP, addany extra OIDC scopes in theAdditional scopes beyond openid,profile, and email field.
    10. ClickContinue.
    11. InConfigure provider, you can configure an attributemapping and an attribute condition. To create anattributemapping, do the following. You can provide either the IdP fieldname or aCEL-formattedexpression that returns a string.
      1. Required: InOIDC 1, enter the subject from the IdP— forexample,assertion.sub.
      2. Optional: To add additional attribute mappings, do the following:
        1. ClickAdd mapping.
        2. InGooglen, wheren is a number, enter oneof theGoogle Cloud-supportedkeys.
        3. In the correspondingOIDCn field, enter the nameof the IdP-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 issuerURL.
        3. In theExtra Attributes Client ID field, enter the clientID.
        4. In theExtra Attributes Client Secret field, enter the clientsecret.
        5. In theExtra Attributes Type list, select an attribute typefor extra attributes.
        6. In theExtra Attributes Filter field, enter a filterexpression that is used when querying the Microsoft Graph API forgroups.
      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.
        3. 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.

    Configure large numbers of groups in Microsoft Entra ID with SAML 2.0

    This section describes how to map up to 400 groups fromMicrosoft Entra ID to Workforce Identity Federation using the SAML 2.0protocol.

    Configure your Microsoft Entra ID application

    To configure your application, do the following:

    1. In the Microsoft Entra ID portal, do the following:
      • To register a new application, follow the instructions inRegister a new application.
      • To update an existing application, do the following:
        • Go toIdentity>Applications>Enterprise applications.
        • Select the application that you want to update.
    2. Create a new client secret in the application by following the instructions inCertificates & secrets. Make sure that you record the client secret value because it's displayed only once.

      Note the following values from the application that you created or updated. You provide the values when you configure the workforce identity pool provider later in this document.

      • Client ID
      • Issuer URI
      • Client Secret
      • Tenant ID

    3. To retrieve the Microsoft Entra ID groups, add the API permission to let Workforce Identity Federation access users' information from Microsoft Entra ID using the Microsoft Graph API and grant admin consent. In Microsoft Entra ID, do the following:

      1. Go toAPI permissions.
      2. ClickAdd a Permission.
      3. SelectMicrosoft API.
      4. SelectApplication permissions.
      5. In the search field, typeUser.ReadBasic.All.
      6. ClickAdd permissions.

      You can retrieve the Microsoft Entra ID groups as group object identifiers (ID) or as group email address for email enabled groups.

      If you choose to retrieve groups as group email addresses, the next step is required.

    4. To retrieve the Microsoft Entra ID groups as group email addresses, do the following. If you retrieve groups as group object identifiers, skip this step.
      1. In the search field, enterGroupMember.Read.All.
      2. ClickAdd permissions.
      3. ClickGrant admin consent for your domain name.
      4. In the dialog that appears, clickYes.
      5. Go to theOverview page of the Microsoft Entra ID application that you created or updated earlier.
      6. ClickEndpoints.

      The issuer URI is the OIDC metadata document URI, omitting the path/.well-known/openid-configuration.

      For example, if the OIDC metadata document ishttps://login.microsoftonline.com/d41ad248-019e-49e5-b3de-4bdfe1fapple/v2.0/.well-known/openid-configuration, the issuer URI ishttps://login.microsoftonline.com/d41ad248-019e-49e5-b3de-4bdfe1fapple/v2.0/.

    Create a workforce identity pool

    gcloud

    To create the workforce identity pool, run the following command:

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

    Replace the following:

    • WORKFORCE_POOL_ID: an ID that you choose to representyour Google Cloud workforce pool. For information on formatting the ID,see theQuery parameterssection in the API documentation.
    • ORGANIZATION_ID: the numeric organization ID ofyour Google Cloud organization for the workforce identity pool.Workforce identity pools are available across all projects andfolders in the organization.
    • DISPLAY_NAME: Optional. A display name for yourworkforce identity pool.
    • DESCRIPTION: Optional. A workforce identity pooldescription.
    • SESSION_DURATION: Optional. The session duration,expressed as a number appended withs—for example,3600s. Sessionduration determines how long the Google Cloud access tokens,console (federated)sign-in sessions, and gcloud CLI sign-in sessions from thisworkforce pool are valid. Session duration defaults to one hour (3600s). Thesession duration value must be between 15 minutes (900s) and 12 hours(43200s).
    Tip: Rungcloud iam workforce-pools create --help to find otherparameters you can customize for this command.

    Console

    To create the workforce identity pool, do the following:

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

      Go to Workforce Identity Pools

    2. Select the organization for your workforce identity pool. Workforceidentity pools are available across all projects and folders in anorganization.

    3. ClickCreate pool and do the following:

      1. In theName field, enter the display name of the pool. The pool IDis automatically derived from the name as you type, and it isdisplayed under theName field. You can update the pool ID byclickingEdit next to the pool ID.

      2. Optional: InDescription, enter a description of the pool.

      3. To create the workforce identity pool, clickNext.

    The workforce identity pool's session duration defaults to one hour (3600s).The session duration determines how long the Google Cloud access tokens,console (federated),and gcloud CLI sign-in sessions from this workforce poolare valid. After you create the pool, you canupdate the pool to seta custom session duration. The session duration must be from 15minutes (900s) to 12 hours (43200s).

    Configure the SAML 2.0 workforce identity pool provider

    gcloud

    To create the SAML workforce identity pool provider, run the following command:

    gcloud iam workforce-pools providers create-samlPROVIDER_ID \    --workforce-pool=WORKFORCE_POOL_ID \    --location=global \    --display-name=DISPLAY_NAME \    --idp-metadata-path=XML_METADATA_PATH \    --attribute-mapping=ATTRIBUTE_MAPPING \    --extra-attributes-issuer-uri=EXTRA_ATTRIBUTES_ISSUER_URI \    --extra-attributes-client-id=EXTRA_ATTRIBUTES_CLIENT_ID \    --extra-attributes-client-secret-value=EXTRA_ATTRIBUTES_CLIENT_SECRET \    --extra-attributes-type=EXTRA_ATTRIBUTES_TYPE  \    --extra-attributes-filter=EXTRA_ATTRIBUTES_FILTER \    --detailed-audit-logging

    Replace the following:

    • PROVIDER_ID: a unique provider ID. The prefixgcp- is reserved and can't be used in a pool or provider ID.
    • WORKFORCE_POOL_ID: the workforce pool ID.
    • DISPLAY_NAME: a display name for the provider.
    • XML_METADATA_PATH: the path to the SAML 2.0 XML metadata file.
    • ATTRIBUTE_MAPPING: the mapping of attributes from Microsoft Entra ID to Google Cloud. For example, to mapgroups andsubject attributes from Microsoft Entra ID, use the following attribute mapping:
      --attribute-mapping="google.groups=assertion.groups, google.subject=assertion.sub"

      For more information, seeAttribute mapping.

    • EXTRA_ATTRIBUTES_ISSUER_URI: the issuer URI from your Microsoft Entra ID application.
    • EXTRA_ATTRIBUTES_CLIENT_ID: the client ID from your Microsoft Entra ID application.
    • EXTRA_ATTRIBUTES_CLIENT_SECRET: the extra client secret from your Microsoft Entra ID application.
    • EXTRA_ATTRIBUTES_TYPE: useazure-ad-groups-mail to retrieve the email addresses of the groups. Useazure-ad-groups-id to retrieve the IDs of the groups.
    • EXTRA_ATTRIBUTES_FILTER: Optional. A filter expression that is used when querying the Microsoft Graph API for groups. You can use this parameter to ensure that the number of groups fetched from the IdP remains below the limit of 400 groups.

      The following example fetches the groups that have the prefixsales in their email ID:

      --extra-attributes-filter='"mail:sales"'

      The following expression fetches groups with a display name that contains the stringsales.

      --extra-attributes-filter='"displayName:sales"'

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

    Console

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

      2. Go to Workforce Identity Pools

    2. In theWorkforce Identity Pools table, select the pool forwhich you want to create the provider.
    3. In theProviders section, click.
    4. In theSelect a Provider vendor list, select your identityprovider (IdP).

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

    5. InSelect an authentication protocol, selectSAML.
    6. In theCreate a provider section, do the following:
      1. InName, enter a name for the provider.
      2. Optional: InDescription, enter a description for theprovider.
      3. InIDP metadata file (XML), select the metadata XML filethat you generated earlier in this guide.
      4. To create a provider that is enabled, make sureEnableprovider is on.
      5. ClickContinue.
    7. In theShare your provider information section, copy theURLs. In your IdP, configure the first URL as the entity ID, which identifies your application to IdP. Configure the other URL as the redirect URI, which informs your IdP where to send the assertion token after logging in.
    8. ClickContinue.
    9. In theConfigure provider section, do the following:
      1. InAttribute mapping, enter a CEL expression forgoogle.subject.
      2. Optional: To enter other mappings, clickAdd mapping andenter other mappings—for example:
        3. google.subject=assertion.subject,google.groups=assertion.attributes['https://example.com/aliases'],attribute.costcenter=assertion.attributes.costcenter[0]
        This example maps the IdP attributesassertion.subject,assertion.attributes['https://example.com/aliases'], andassertion.attributes.costcenter[0] to the Google Cloudattributesgoogle.subject,google.groups,andgoogle.costcenter, respectively.
      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 issuerURL.
        3. In theExtra Attributes Client ID field, enter the clientID.
        4. In theExtra Attributes Client Secret field, enter the clientsecret.
        5. In theExtra Attributes Type list, select an attribute typefor extra attributes.
        6. In theExtra Attributes Filter field, enter a filterexpression that is used when querying the Microsoft Graph API forgroups.
      4. Optional: To add an attribute condition, clickAdd conditionand enter a CEL expression representing an attribute condition.For example, to limit theipaddr attribute to a certain IP rangeyou can set the conditionassertion.attributes.ipaddr.startsWith('98.11.12.'). This example condition ensures that only users with an IP address that starts with98.11.12. can sign in using this workforce provider.
        5. 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.
      5. ClickContinue.
      6. 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.

    10. To create the provider, clickSubmit.

    Grant IAM roles to groups

    In this section you grant roles to groups on Google Cloud resources. To learn more about Workforce Identity Federation principal identifiers, seeRepresent workforce pool users in IAM policies.

    The following example grants the Storage Admin role (roles/storage.admin) to users in a Microsoft Entra ID group.

    gcloud projects add-iam-policy-bindingPROJECT_ID \    --role="roles/storage.admin" \    --member="principalSet://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/group/GROUP_ID"

    Replace the following:

    • PROJECT_ID: the project ID
    • WORKFORCE_POOL_ID: the workforce identity pool ID
    • GROUP_ID: the group identifier, which depends on the value of--extra-attributes-type that was used to create the workforce identity pool provider, as follows:
      • azure-ad-groups-mail: the group identifier is an email address—for example:admin-group@altostrat.com
      • azure-ad-groups-id: the group identifier is a UUID for the group—for example:abcdefgh-0123-0123-abcdef

    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.

    Console (federated) sign-in

    To sign in to the Google Cloud Workforce Identity Federation console, also known as the console (federated), do the following:

    1. Go to the console (federated) sign-in page.

      Go to console (federated)

    2. Enter the provider name, which is formatted as follows:
      locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID

      3. If prompted, enter user credentials in Microsoft Entra ID.

      If you start an IdP-initiated sign-on, use the following for therelay URL:https://console.cloud.google/.

    gcloud CLI browser-based sign-in

    To sign in to gcloud CLI using a browser-based sign-in flow, do thefollowing:

    Create a configuration file

    To create the login configuration file, run the following command. You can optionally activate the file as the default for the gcloud CLI by adding the--activate flag. You can then rungcloud auth login without specifying the configuration file path each time.

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

    Replace the following:

    • WORKFORCE_POOL_ID: the workforce pool ID
    • PROVIDER_ID: the provider ID
    • LOGIN_CONFIG_FILE_PATH: the path to a configuration file that you specify—for example,login.json

    The file contains the endpoints used by the gcloud CLI to enable the browser-based authentication flow and set the audience to the IdP that was configured in the workforce identity pool provider. The file doesn't contain confidential information.

    The output looks similar to the following:

    {"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"}

    Caution: We recommend that you first ensure that the contents of this file are correct and then safeguard the file—for example, by making it read-only and restricting access with an ACL. The file isn't validated; a malicious actor with write access to this file can change the endpoints and intercept credentials.

    To stopgcloud auth login from using this configuration file automatically, you can unset it by runninggcloud config unset auth/login_config_file.

    Sign in using browser-based authentication

    To authenticate using browser-based sign-in authentication, you can use one of the following methods:

    • If you used the--activate flag when you created the configuration file, or if you activated the configuration file withgcloud config set auth/login_config_file, the gcloud CLI uses your configuration file automatically:

      gcloudauthlogin

    • To sign in by specifying the location of the configuration file, run the following command:

      gcloudauthlogin--login-config=LOGIN_CONFIG_FILE_PATH
    • To use an environment variable to specify the location of the configuration file, setCLOUDSDK_AUTH_LOGIN_CONFIG_FILE to the configuration path.

    Disable browser-based sign-in

    To discontinue using the login configuration file, do the following:

    • If you used the--activate flag when you created the configuration file, or if you activated the configuration file withgcloud config set auth/login_config_file, you must run the following command to unset it:

      gcloudconfigunsetauth/login_config_file
    • Clear theCLOUDSDK_AUTH_LOGIN_CONFIG_FILE environment variable, if it is set.

    gcloud CLI headless sign-in

    To sign in to Microsoft Entra ID with the gcloud CLI, do thefollowing:

    OIDC

    1. Follow the steps inSend the sign-in request.Sign the user into your application with Microsoft Entra ID usingOIDC.

    2. Copy the ID token from theid_token parameter of the redirect URLand save it to a file in a secure location on your local machine. Ina later step, you setPATH_TO_OIDC_ID_TOKEN to thepath to this file.

    3. Generate a configuration file similar to the example later in thisstep by running the following command:

      gcloudiamworkforce-poolscreate-cred-config\locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID\--subject-token-type=urn:ietf:params:oauth:token-type:id_token\--credential-source-file=PATH_TO_OIDC_ID_TOKEN\--workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT\--output-file=config.json

      Replace the following:

      • WORKFORCE_POOL_ID: the workforce identitypool ID.
      • WORKFORCE_PROVIDER_ID: the workforce identitypool provider ID.
      • PATH_TO_OIDC_ID_TOKEN: the path to the filelocation where the IdP token is stored.
      • WORKFORCE_POOL_USER_PROJECT: the project number or IDused for quota and billing. The principal must haveserviceusage.services.use permission on this project.

      When the command completes, the following config file is created byMicrosoft Entra ID:

      {"type":"external_account","audience":"//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID","subject_token_type":"urn:ietf:params:oauth:token-type:id_token","token_url":"https://sts.googleapis.com/v1/token","workforce_pool_user_project":"WORKFORCE_POOL_USER_PROJECT","credential_source":{"file":"PATH_TO_OIDC_CREDENTIALS"}}

    4. Open the gcloud CLI and run the following command:

      gcloudauthlogin--cred-file=PATH_TO_OIDC_CREDENTIALS

      ReplacePATH_TO_OIDC_CREDENTIALS with the path to theoutput file from a previous step.

      The gcloud CLI transparently posts your credentials to theSecurity Token Service endpoint. In the endpoint, it is exchanged fortemporary Google Cloud access tokens.

      You can now run gcloud CLI commands toGoogle Cloud.

    SAML

    1. Sign in a user to your Microsoft Entra ID application and get the SAMLresponse.

    2. Save the SAML response returned by Microsoft Entra ID in a securelocation on your local machine, then store the path as follows:

      SAML_ASSERTION_PATH=SAML_ASSERTION_PATH

    3. To generate a credential configuration file, run the followingcommand:

      gcloudiamworkforce-poolscreate-cred-config\locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID\--subject-token-type=urn:ietf:params:oauth:token-type:saml2\--credential-source-file=SAML_ASSERTION_PATH\--workforce-pool-user-project=PROJECT_ID\--output-file=config.json

      Replace the following:

      • WORKFORCE_PROVIDER_ID: the ID of theworkforce identity pool provider that you created earlier in thisguide
      • WORKFORCE_POOL_ID: the ID of the workforceidentity pool that you created earlier in this guide
      • SAML_ASSERTION_PATH: the path of the SAMLassertion file
      • PROJECT_ID: the project ID

      The configuration file that is generated looks similar to thefollowing:

      {"type":"external_account","audience":"//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID","subject_token_type":"urn:ietf:params:oauth:token-type:saml2","token_url":"https://sts.googleapis.com/v1/token","credential_source":{"file":"SAML_ASSERTION_PATH"},"workforce_pool_user_project":"PROJECT_ID"}

    4. To login to the gcloud CLI usingWorkforce Identity Federation token exchange, run the followingcommand:

      gcloudauthlogin--cred-file=config.json

      The gcloud CLI then transparently exchanges your MicrosoftEntra ID credentials for temporary Google Cloud access tokens.The access tokens let you access Google Cloud.

      You see output similar to the following:

      Authenticated with external account user credentials for:[principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/USER_ID].

    5. To list the credentialed accounts and your active account,run the following command:

      gcloudauthlist

    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.

    Console (federated)

    To test that you have access using the console (federated), do thefollowing:

    • Go to the Cloud Storage page.

      Go to Cloud Storage

    • Verify that you can see a list of existing buckets for theTEST_PROJECT_ID.

    gcloud CLI

    To test that you have access using the gcloud CLI, you can listCloud Storage buckets and objects for the project that you haveaccess to. To do this, run the following command. The principal must have theserviceusage.services.use permission on the specified project.

    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

    Important: SCIM is available only for Gemini Enterprise.

    Important: SCIM is available only for Gemini Enterprise.

    This section describes how to configure a SCIM tenant in a workforce identity pool.

    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.

    To configureSystem for Cross-domain Identity Management (SCIM), you must do the following:

    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:

    OIDC

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

    Replace the following:

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

    SAML

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

    Replace the following:

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

    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:

    Google attributeWorkforce identity pool provider mappingSCIM tenant mapping
    google.subjectassertion.oiduser.externalId
    google.subjectassertion.emailuser.emails[0].value
    google.subjectassertion.email.lowerAscii()user.emails[0].value.lowerAscii()
    google.subjectassertion.preferred_usernameuser.userName
    google.group make sure you update your provider with--scim-usage=enabled-for-groupsN/Agroup.externalId

    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

    Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

    Last updated 2025-12-15 UTC.