Configure Workforce Identity Federation with Microsoft Entra ID and sign in users

This document shows you how to configure Workforce Identity Federation with the Microsoft Entra ID identity provider (IdP) and manage access to Google Cloud. Federated users can then access Google Cloud services that support Workforce Identity Federation. You can use either the OIDC protocol or SAML 2.0 protocol to federate identities.

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:

   gcloud init

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

3. In Microsoft Entra ID, make sure that ID tokens are enabled for implicit flow. For more information, see Enable 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 or Google Cloud products, you must provide Essential Contacts. For more information, see the Workforce Identity Federation overview.

Costs

Workforce Identity Federation is available as a no-cost feature. However, Workforce Identity Federation detailed audit logging uses Cloud Logging. To learn about Logging pricing, see Google Cloud Observability pricing.

Required roles

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

You might also be able to get the required permissions through custom roles or other predefined roles.

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

Create a Microsoft Entra ID application

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

Create a workforce identity pool

gcloud iam workforce-pools create WORKFORCE_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 a workforce identity pool provider to 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 ID application integration, using the OIDC protocol, do the following:

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

   1. Go to the Overview page of your Microsoft Entra ID application registration.
   2. Click Endpoints.
   3. Open the OpenID Connect metadata document in a new tab.
   4. In the JSON, copy the value of issuer.

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

   1. Go to the Overview page of your Microsoft Entra ID application registration.
   2. Click Endpoints.
   3. In Application (client) ID, copy the value.

3. To create an OIDC workforce identity pool provider for web-based sign-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 uses authorization 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. In Certificates & secrets, click the Client secrets tab.

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

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

      5. To create the client secret, click Add.

      6. In the Client secrets tab, find your new client secret.

      7. In the Value column for your new client secret, click content_copy Copy.

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

      gcloud iam workforce-pools providers create-oidc WORKFORCE_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 prefix gcp- 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 with https; 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 the aud 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: An attribute mapping. For Microsoft Entra ID with OIDC authentication, we recommend the following attribute mappings:

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

        This example maps the IdP attributes assertion.oid, assertion.groups, and assertion.preferred_username to the Google Cloud attributes google.subject, google.groups, and google.display_name, respectively.

      • ATTRIBUTE_CONDITION: An attribute condition; for example, to limit the ipaddr attribute to a certain IP range you can set the condition assertion.ipaddr.startsWith('98.11.12.') .
      • JWK_JSON_PATH: An optional path to a locally 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, see manage OIDC JWKs.

      • Workforce Identity Federation detailed 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, see General attribute mapping errors. To learn about Logging pricing, see Google Cloud Observability pricing.

        To disable detailed audit logging for a workforce identity pool provider, omit the --detailed-audit-logging flag when you run gcloud iam workforce-pools providers create. To disable detailed audit logging, you can also update 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 the implicit flow for web sign-in, do the following:

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

      1. Go to your Microsoft Entra ID application registration.
      2. In Authentication, select the ID token checkbox.
      3. Click Save.

   2. To create the provider, run the following command:

      gcloud iam workforce-pools providers create-oidc WORKFORCE_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 prefix gcp- 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 with https; 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 the aud 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: An attribute mapping. For Microsoft Entra ID with OIDC authentication, we recommend the following attribute mappings:

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

        This example maps the IdP attributes assertion.oid, assertion.groups, and assertion.preferred_username to the Google Cloud attributes google.subject, google.groups, and google.display_name, respectively.

      • ATTRIBUTE_CONDITION: An attribute condition; for example, to limit the ipaddr attribute to a certain IP range you can set the condition assertion.ipaddr.startsWith('98.11.12.') .
      • JWK_JSON_PATH: An optional path to a locally 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, see manage OIDC JWKs.

      • Workforce Identity Federation detailed 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, see General attribute mapping errors. To learn about Logging pricing, see Google Cloud Observability pricing.

        To disable detailed audit logging for a workforce identity pool provider, omit the --detailed-audit-logging flag when you run gcloud iam workforce-pools providers create. To disable detailed audit logging, you can also update 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 uses authorization code flow for 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. In Certificates & secrets, click the Client secrets tab.

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

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

      5. To create the client secret, click Add.

      6. In the Client secrets tab, find your new client secret.

      7. In the Value column for your new client secret, click content_copy Copy.

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

      Go to Workforce Identity Pools

   2. In the Workforce Identity Pools table, select the pool for which you want to create the provider.
   3. In the Providers section, click addAdd Provider.
   4. In the Select a Provider vendor list, select your IdP.

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

   5. In Select an authentication protocol, select OpenID Connect (OIDC).
   6. In the Create a provider section, do the following:
      1. In Name, enter the name for the provider.
      2. In Description, enter the description for the provider.
      3. In Issuer (URL), enter the issuer URI. The OIDC issuer URI must be in a valid URI format and start with https; for example, https://example.com/oidc.
      4. In Client ID, enter the OIDC client ID that is registered with your OIDC IdP; the ID must match the aud claim of the JWT that is issued by your IdP.
      5. To create a provider that is enabled, make sure Enable provider is on.
      6. Click Continue.
   7. In the Share your provider information with IdP section, copy the URL. In your IdP, configure this URL as the redirect URI, which informs your IdP where to send the assertion token after logging in.
   8. Click Continue.
   9. In the Configure OIDC Web Sign-in section, do the following:
      1. In the Flow type list, select Code.
      2. In the Assertion claims behavior list, select either of the following:
         • User info and ID token
         • Only ID token
      3. In the Client secret field, enter the client secret from your IdP.

   10. Click Continue.
   11. In the Configure provider section, for Detailed logging, click the Enable attribute value audit logging toggle.

       Workforce Identity Federation detailed 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, see General attribute mapping errors. To learn about Logging pricing, see Google Cloud Observability pricing.

       To disable detailed audit logging for a workforce identity pool provider, leave the Enable attribute value audit logging toggle off when you create the provider. To disable detailed audit logging, you can also update the provider.

   12. To create the provider, click Submit.

   After the provider is created, you are redirected to the provider attributes page.

   To configure attribute mappings and conditions, do the following:

   1. When prompted, sign in to your external IdP to validate the default attribute mappings.
   2. On the provider attributes page, view and edit the attribute mappings and conditions:
      1. To add or edit attribute mappings, do the following:
         1. Click Add mapping to add a new mapping, or edit the existing mappings.
         2. In the Google n field, where n is a number, select a Google Cloud-supported key.
         3. In the corresponding OIDC n field, enter the IdP attribute name or a CEL expression. For Microsoft Entra ID with OIDC authentication, we recommend the following attribute mappings:

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

            This example maps the IdP attributes assertion.oid, assertion.groups, and assertion.preferred_username to the Google Cloud attributes google.subject, google.groups, and google.display_name, respectively.

      2. To increase the number of groups, do the following:
         1. Click Enable for extra attributes.
         2. In the subtask that opens, enter the following details:
            1. In the Extra Attributes Issuer URI field, enter the issuer URL.
            2. In the Extra Attributes Client ID field, enter the client ID.
            3. In the Extra Attributes Client Secret field, enter the client secret.
            4. In the Extra Attributes Type list, select an attribute type for extra attributes.
            5. In the Extra Attributes Filter field, enter a filter expression to be used when querying the Microsoft Graph API for groups.
            6. Click Enable.

         After you enable extra attributes, you can click Edit to reopen the subtask and edit the details, or click Disable to turn off extra attributes.

      3. To add an attribute condition, do the following:
         1. Click Add condition.
         2. In the Attribute Conditions field, enter a condition in CEL format; for example, to limit the ipaddr attribute to a certain IP range you can set the condition assertion.ipaddr.startsWith('98.11.12.') .
   3. To validate your mappings, click Save and refetch token.
   4. To complete the setup, click Save and exit.

   Implicit flow

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

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

      1. Go to your Microsoft Entra ID application registration.
      2. In Authentication, select the ID token checkbox.
      3. Click Save.

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

      Go to Workforce Identity Pools

   2. In the Workforce Identity Pools table, select the pool for which you want to create the provider.
   3. In the Providers section, click add Add Provider.
   4. In the Select a Provider vendor list, select your IdP.

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

   5. In Select an authentication protocol, select OpenID Connect (OIDC).
   6. In the Create a provider section, do the following:
      1. In Name, enter the name for the provider.
      2. In Description, enter the description for the provider.
      3. In Issuer (URL), enter the issuer URI. The OIDC issuer URI must be in a valid URI format and start with https; for example, https://example.com/oidc.
      4. In Client ID, enter the OIDC client ID that is registered with your OIDC IdP; the ID must match the aud claim of the JWT that is issued by your IdP.
      5. To create a provider that is enabled, make sure Enable provider is on.
      6. Click Continue.
   7. In the Share your provider information with IdP section, copy the URL. In your IdP, configure this url as the redirect URI, which informs your IdP where to send the assertion token after logging in.
   8. Click Continue.
   9. In the Configure OIDC Web Sign-in section, do the following:
      1. In the Flow type list, select ID Token.
      2. In the Assertion claims behavior list, ID token is selected.
   10. Click Continue.
   11. In the Configure provider section, in Detailed logging, click the Enable attribute value audit logging toggle.

       Workforce Identity Federation detailed 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, see General attribute mapping errors. To learn about Logging pricing, see Google Cloud Observability pricing.

       To disable detailed audit logging for a workforce identity pool provider, leave the Enable attribute value audit logging toggle off when you create the provider. To disable detailed audit logging, you can also update the provider.

   12. To create the provider, click Submit.

   After the provider is created, you are redirected to the provider attributes page.

   To configure attribute mappings and conditions, do the following:

   1. When prompted, sign in to your external IdP to validate the default attribute mappings.
   2. On the provider attributes page, view and edit the attribute mappings and conditions:
      1. To add or edit attribute mappings, do the following:
         1. Click Add mapping to add a new mapping, or edit the existing mappings.
         2. In the Google n field, where n is a number, select a Google Cloud-supported key.
         3. In the corresponding OIDC n field, enter the IdP attribute name or a CEL expression. For Microsoft Entra ID with OIDC authentication, we recommend the following attribute mappings:

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

            This example maps the IdP attributes assertion.oid, assertion.groups, and assertion.preferred_username to the Google Cloud attributes google.subject, google.groups, and google.display_name, respectively.

      2. To increase the number of groups, do the following:
         1. Click Enable for extra attributes.
         2. In the subtask that opens, enter the details:
            1. In the Extra Attributes Issuer URI field, enter the issuer URL.
            2. In the Extra Attributes Client ID field, enter the client ID.
            3. In the Extra Attributes Client Secret field, enter the client secret.
            4. In the Extra Attributes Type list, select an attribute type for extra attributes.
            5. In the Extra Attributes Filter field, enter a filter expression to be used when querying the Microsoft Graph API for groups.
            6. Click Enable.

         After you enable extra attributes, you can click Edit to reopen the subtask and edit the details, or click Disable to turn off extra attributes.

      3. To add an attribute condition, do the following:
         1. Click Add condition.
         2. In the Attribute Conditions field, enter a condition in CEL format; for example, to limit the ipaddr attribute to a certain IP range you can set the condition assertion.ipaddr.startsWith('98.11.12.') .
   3. To validate your mappings, click Save and refetch token.
   4. To complete the setup, click Save and exit.

Create a SAML 2.0 workforce identity pool provider

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

2. Set the audience for SAML assertions. It is usually the SP Entity ID field in your IdP configuration. You must set 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 your SAML IdP, and do one of the following:

   • To set up browser-based sign-in through the Google Cloud console or another 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 workforce identity pool provider that you create later in this document.

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

     localhost
     

   See Set up user access to the console for more details on configuring console sign-in.

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

   • A SAML entity ID for your IdP.
   • The single-sign-on URL for your IdP.
   • At least one signing public key. See