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

This guide shows you how to configure Workforce Identity Federation with Microsoft Entra ID and manage access to Google Cloud. Users of Microsoft Entra ID identity can then access Google Cloud services that support Workforce Identity Federation.

Before you begin

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

2. After installing the Google Cloud CLI, configure the gcloud CLI to use your federated identity and then initialize it by running the following command:

   gcloud init

   Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.
3. In Microsoft Entra ID, ensure that ID Tokens are enabled for implicit flow. For more information, see [Enable the implicit flow](https://learn.microsoft.com/en-us/azure/active-directory-b2c/tutorial-register-applications#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.

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.

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

Create a workforce identity pool

Console

To create the workforce identity pool, do the following:

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

   Go to Workforce Identity Pools

2. Click Create pool and do the following:

   1. In the Name field, enter the display name of the pool. The pool ID is automatically derived from the name as you type, and it is displayed under the Name field. You can update the pool ID by clicking Edit next to the pool ID.

   2. Optional: In Description, enter a description of the pool.

   3. Session duration is set by default. To enter a custom session duration, click Edit. Session duration determines how long the Google Cloud access tokens, console (federated) sign-in sessions, and gcloud CLI sign-in sessions from this workforce pool are valid. The duration must be greater than 15 minutes (900s) and less than 12 hours (43200s). If session duration is not set, it defaults to a duration of one hour (3600s).

   4. To create the pool in the enabled state, make sure that Enabled Pool is on.

   5. To create the workforce identity pool, click Next.

gcloud

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

gcloud iam workforce-pools create WORKFORCE_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 represent your Google Cloud workforce pool. For information on formatting the ID, see the Query parameters section in the API documentation.
• ORGANIZATION_ID: the numeric organization ID of your Google Cloud organization.
• DISPLAY_NAME: Optional. A display name for your workforce identity pool.
• DESCRIPTION: Optional. A workforce identity pool description.
• SESSION_DURATION: Optional. The session duration, which determines how long the Google Cloud access tokens, console (federated) sign-in sessions, and gcloud CLI sign-in sessions from this workforce pool are valid. The duration must be greater than 15 minutes (900s) and less than 12 hours (43200s). If session duration is not set, it defaults to a duration of one hour (3600s).

Tip: Run gcloud iam workforce-pools create --help to find other parameters you can customize for this command.

Create a Microsoft Entra ID app

This section provides the steps to create a Microsoft Entra ID app using the Microsoft Entra admin portal. For additional details, see What is authentication.

Note: In this guide, you create a custom attribute called department to demonstrate an attribute mapping. This task is for illustrative purposes only.

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

OIDC

To create a Microsoft app registration that uses the OIDC protocol, perform the following steps:

1. Sign in to the Microsoft Entra administrator portal.
2. Go to Identity > Applications > App registrations.

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

   1. Click New registration.
   2. Enter a name for your app.
   3. In Supported account types, select an option.

   4. In the Redirect URI section, in the Select a platform drop-down list, select Web. In the text field, enter a redirect URL. Your users are redirected to this URL after they successfully sign in. If you are configuring access to the console (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 ID of the workforce pool that you created earlier in this guide.
      • WORKFORCE_PROVIDER_ID: a workforce identity provider ID of your choice—for example: azure-ad-oidc-provider. For information on formatting the ID, see the Query parameters section in the API documentation.

   5. To create the app registration, click Register.

4. Optional: To configure a groups claim, do the following:

   1. Go to your Microsoft Entra ID app registration.
   2. Click Token configuration.
   3. Click Add groups claim. To use the example attribute mapping that is provided later in this guide, you must create a custom department attribute.
   4. Select the group types to return. For more details, refer to Configuring groups optional claims.

SAML

To create a Microsoft application that uses the SAML protocol, perform the following steps:

1. Sign in to the Microsoft Azure Portal.
2. Go to Azure Active Directory > Enterprise applications.

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

   1. Click New application > Create your own application.
   2. Enter a name for your app.
   3. Click Create.
   4. Go to Single sign-on > SAML.

   5. Update the Basic SAML Configuration as follows:

      1. In the Identifier (Entity ID) field, enter the following value:

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

      2. In the Reply URL (Assertion Consumer Service URL) field, enter a redirect URL. Your users are redirected to this URL after they successfully sign in. If you are configuring access to the console (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 ID of the workforce identity pool that you created earlier in this guide.
         • WORKFORCE_PROVIDER_ID: a workforce identity provider ID of your choice; for example: azure-ad-oidc-provider. For information on formatting the ID, see the Query parameters section in the API documentation.

      3. If you want to enable IdP-initiated sign-on, set the Relay State field to the following value:

         https://console.cloud.google/
         

      4. To save the SAML app configuration, click Save.

4. To configure a group claim, do the following. To use the example attribute mapping that is provided later in this guide, you must create a custom department attribute.

   1. Go to your Microsoft Entra ID app.
   2. Click Single sign-on.
   3. In the Attributes & Claims section, click Edit.
   4. Click Add a group claim.
   5. Select the group type to return. For more details, refer to Add group claims to tokens for SAML applications using SSO configuration.

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 app integration, using the OIDC protocol, do the following:

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

   1. Go to your Microsoft Entra ID app 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 app, do the following:

   1. Go to your Microsoft Entra ID app registration.
   2. In Application (client) ID, copy the value.

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

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

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

      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 table, click Add Provider.

      4. In Select a protocol, select Open ID Connect (OIDC).

      5. In Create a pool provider, do the following:

         1. In Name, enter a name for the provider.
         2. 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.
         3. Enter the 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.
         4. To create a provider that is enabled, make sure Enabled Provider is on.
         5. Click Continue.

      6. In Response type do the following. Response type is used only for a web-based single-sign-on flow.

         1. In Response type, select Code.
         2. In Client secret, enter the client secret from your IdP.

         3. In Assertion claims behavior, select either of the following:

            • User info and ID token
            • Only ID token

         4. Click Continue.

      7. In Configure provider, you can configure an attribute mapping and an attribute condition. To create an attribute mapping, do the following. You can provide either the IdP field name or a CEL-formatted expression that returns a string.

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

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

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

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

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

            1. Click Add mapping.
            2. In Google n, where n is a number, enter one of the Google Cloud-supported keys.
            3. In the corresponding OIDC n field, enter the name of the IdP-specific field to map, in CEL format.

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

            Warning: If your multi-tenant IdP has a single issuer URI, you must use attribute conditions to ensure that access is restricted to the correct tenant. For more information, see Use attribute conditions when federating with GitHub or other multi-tenant identity providers.
            1. Click Add condition.
            2. In Attribute Conditions, 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.') .

      8. To create the provider, click Submit.

   Implicit flow

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

   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 table, click Add Provider.

   4. In Select a protocol, select Open ID Connect (OIDC).

   5. In Create a pool provider, do the following:

      1. In Name, enter a name for the provider.
      2. 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.
      3. Enter the 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.
      4. To create a provider that is enabled, make sure Enabled Provider is on.
      5. Click Continue.

   6. In Response type do the following. Response type is used only for a web-based single-sign-on flow.

      1. In Response type, select ID token.
      2. Click Continue.

   7. In Configure provider, you can configure an attribute mapping and an attribute condition. To create an attribute mapping, do the following. You can provide either the IdP field name or a CEL-formatted expression that returns a string.

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

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

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

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

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

         1. Click Add mapping.
         2. In Google n, where n is a number, enter one of the Google Cloud-supported keys.
         3. In the corresponding OIDC n field, enter the name of the IdP-specific field to map, in CEL format.

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

         1. Click Add condition.

         2. In Attribute Conditions, 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.') .

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

   8. To create the provider, click Submit.

   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 app, 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 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" \
          --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.sub,
        google.groups=assertion.groups,
        google.display_name=assertion.preferred_username
        

        This example maps the IdP attributes subject, groups, and 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.') .
      Warning: If your multi-tenant IdP has a single issuer URI, you must use attribute conditions to ensure that access is restricted to the correct tenant. For more information, see Use attribute conditions when federating with GitHub or other multi-tenant identity providers.
      • 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.
      Note: Local OIDC JWKs can be uploaded through implicit flow or code flow, but can only be used in programmatic flow, in which you directly call the STS /token endpoint with a credential from the third-party IdP to exchange for a Google Cloud access token for your workforce pool.
      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 app, do the following:

      1. Go to your Microsoft Entra ID app 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" \
          --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.sub,
        google.groups=assertion.groups,
        google.display_name=assertion.preferred_username
        

        This example maps the IdP attributes subject, groups, and 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.') .
      Warning: If your multi-tenant IdP has a single issuer URI, you must use attribute conditions to ensure that access is restricted to the correct tenant. For more information, see Use attribute conditions when federating with GitHub or other multi-tenant identity providers.
      • 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.
      Note: Local OIDC JWKs can be uploaded through implicit flow or code flow, but can only be used in programmatic flow, in which you directly call the STS /token endpoint with a credential from the third-party IdP to exchange for a Google Cloud access token for your workforce pool.
      In the command response, POOL_RESOURCE_NAME is the name of the pool; for example, locations/global/workforcePools/enterprise-example-organization-employees.

Create a SAML 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. If you plan to set up user access to the console, in your SAML IdP, set the redirect URL or Assertion Consumer Service (ACS) URL field to the following URL:

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

   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 Key requirements later in this guide for details on signing keys.

Console

To configure the SAML provider using the Google Cloud console, do the following:

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 table, click Add Provider.

4. In Select a protocol, select SAML.

5. In Create a pool provider do the following:

   1. In Name, enter a name for the provider.

   2. Optional: In Description, enter a description for the provider.

   3. In IDP metadata file (XML), select the metadata XML file that you generated earlier in this guide.

   4. Ensure that Enabled provider is enabled.

   5. Click Continue.

6. In Configure provider, do the following:

   1. In Attribute mapping, enter a CEL expression for google.subject.

   2. Optional: To enter other mappings, click Add mapping and enter other mappings—for example:

      google.subject=assertion.subject,
      google.groups=assertion.attributes['https://example.com/aliases'],
      attribute.costcenter=assertion.attributes.costcenter[0]

      This example maps the IdP attributes assertion.subject, assertion.attributes['https://example.com/aliases'], and assertion.attributes.costcenter[0] to the Google Cloud attributes google.subject, google.groups, and google.costcenter, respectively.

   3. Optional: To add an attribute condition, click Add condition and enter a CEL expression representing an attribute condition. For example, to limit the ipaddr attribute to a certain IP range you can set the condition assertion.attributes.ipaddr.startsWith('98.11.12.'). This example condition ensures that only users with an IP address that starts with 98.11.12. can sign in using this workforce provider.

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

   4. Click Continue.

7. To create the provider, click Submit.

gcloud

To save the SAML metadata for your Microsoft Entra ID app, do the following:

1. Go to your Microsoft Entra ID app.
2. Click Single sign-on.
3. In the SAML Certificates section, download the Federation Metadata XML.
4. Save the metadata as a local XML file.

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

gcloud iam workforce-pools providers create-saml WORKFORCE_PROVIDER_ID \
    --workforce-pool="WORKFORCE_POOL_ID" \
    --display-name="DISPLAY_NAME" \
    --description="DESCRIPTION" \
    --idp-metadata-path="XML_METADATA_PATH" \
    --attribute-mapping="ATTRIBUTE_MAPPING" \
    --attribute-condition="ATTRIBUTE_CONDITION" \
    --location=global

Replace the following:

• WORKFORCE_PROVIDER_ID: The provider ID.
• WORKFORCE_POOL_ID: the workforce identity pool ID.
• DISPLAY_NAME: The display name.
• DESCRIPTION: A description.
• XML_METADATA_PATH: The path to the XML-formatted metadata file with configuration metadata for the SAML identity provider.

• ATTRIBUTE_MAPPING: The attribute mapping—for example:

  google.subject=assertion.subject,
  google.groups=assertion.attributes['https://example.com/aliases'],
  attribute.costcenter=assertion.attributes.costcenter[0]

  This example maps the IdP attributes assertion.subject, assertion.attributes['https://example.com/aliases'], and assertion.attributes.costcenter[0] to the Google Cloud attributes google.subject, google.groups, and google.costcenter, respectively.

• ATTRIBUTE_CONDITION: An optional attribute condition. For example, to limit the ipaddr attribute to a certain IP range you can set the condition assertion.attributes.ipaddr.startsWith('98.11.12.'). This example condition ensures that only users with an IP address that starts with 98.11.12. can sign in using this workforce provider.

Optional: Accept encrypted SAML assertions from your IdP

To enable your SAML 2.0 IdP to produce encrypted SAML assertions that can be accepted by workforce identity federation, do the following:

• In workforce identity federation, do the following:
• Create an asymmetric key pair for your workforce identity pool provider.
• Download a certificate file that contains the public key.
• Configure your SAML IdP to use the public key to encrypt SAML assertions it issues.
• In your IdP, do the following:
• Enable assertion encryption, also known as token encryption.
• Upload the public key that you created in workforce identity federation.
• Confirm that your IdP produces encrypted SAML assertions.

Note that, even with SAML encryption provider keys configured, workforce identity federation can still process a plaintext assertion.

Create workforce identity federation SAML assertion encryption keys

This section guides you through creating an asymmetric key pair that enables workforce identity federation to accept encrypted SAML assertions.

Google Cloud uses the private key to decrypt the SAML assertions that your IdP issues. To create an asymmetric key pair for use with SAML encryption, run the following command. To learn more, see Supported SAML encryption algorithms.

gcloud iam workforce-pools providers keys create KEY_ID \
    --workforce-pool WORKFORCE_POOL_ID \
    --provider WORKFORCE_PROVIDER_ID \
    --location global \
    --use encryption \
    --spec KEY_SPECIFICATION

Replace the following:

• KEY_ID: a key name of your choice
• WORKFORCE_POOL_ID: the pool ID
• WORKFORCE_PROVIDER_ID: the workforce identity pool provider ID
• KEY_SPECIFICATION: the key specification, which can be one of rsa-2048, rsa-3072, and rsa-4096.

After the key pair is created, to download the public key into a certificate file, execute the following command. Only workforce identity federation has access to the private key.

gcloud iam workforce-pools providers keys describe KEY_ID \
    --workforce-pool WORKFORCE_POOL_ID \
    --provider WORKFORCE_PROVIDER_ID \
    --location global \
    --format "value(keyData.key)" \
    > CERTIFICATE_PATH

Replace the following:

• KEY_ID: the key name
• WORKFORCE_POOL_ID: the pool ID
• WORKFORCE_PROVIDER_ID: the workforce identity pool provider ID
• CERTIFICATE_PATH: the path to write the certificate to—for example, saml-certificate.cer or saml-certificate.pem

Configure your SAML 2.0-compliant IdP to issue encrypted SAML assertions

To configure Microsoft Entra ID to encrypt SAML tokens, see Configure Azure Active Directory SAML token encryption.

After you configure your IdP to encrypt SAML assertions, we recommend that you check to make sure that the assertions it generates are actually encrypted. Even with SAML assertion encryption configured, workforce identity federation can still process plaintext assertions.

Delete workforce identity federation encryption keys

To delete SAML encryption keys run the following command:

  gcloud iam workforce-pools providers keys delete KEY_ID \
      --workforce-pool WORKFORCE_POOL_ID \
      --provider WORKFORCE_PROVIDER_ID \
      --location global

Replace the following:

• KEY_ID: the key name
• WORKFORCE_POOL_ID: the pool ID
• WORKFORCE_PROVIDER_ID: the workforce identity pool provider ID

Supported SAML encryption algorithms

Workforce identity federation supports the following key transport algorithms:

• http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p
• http://www.w3.org/2009/xmlenc11#rsa-oaep"
• http://www.w3.org/2001/04/xmlenc#rsa-1_5"

Workforce identity federation supports the following block encryption algorithms:

• http://www.w3.org/2001/04/xmlenc#aes128-cbc
• http://www.w3.org/2001/04/xmlenc#aes192-cbc
• http://www.w3.org/2001/04/xmlenc#aes256-cbc
• http://www.w3.org/2009/xmlenc11#aes128-gcm
• http://www.w3.org/2009/xmlenc11#aes256-gcm

Manage access to Google Cloud resources

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

In this example, you grant an Identity and Access Management (IAM) role on a sample project. Users can then sign in and use this project to access Google Cloud products.

Note: The sample project used here can be different from the project you used to set up Workforce Identity Federation.

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

For single identity

To grant the Storage Admin (roles/storage.admin) role to a single identity for project TEST_PROJECT_ID, run the following command:

gcloud projects add-iam-policy-binding TEST_PROJECT_ID \
    --role="roles/storage.admin" \
    --member="principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/SUBJECT_VALUE"

Replace the following:

• TEST_PROJECT_ID: ID of the project
• WORKFORCE_POOL_ID: the workforce identity pool ID
• SUBJECT_VALUE: the user identity

Using mapped department attribute

To grant the Storage Admin (roles/storage.admin) role to all identities within a specific department for project TEST_PROJECT_ID, run the following command:

gcloud projects add-iam-policy-binding TEST_PROJECT_ID \
    --role="roles/storage.admin" \
    --member="principalSet://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/attribute.department/DEPARTMENT_VALUE"

Replace the following:

• TEST_PROJECT_ID: ID of the project
• WORKFORCE_POOL_ID: the workforce identity pool ID
• DEPARTMENT_VALUE: the mapped attribute.department value

Using mapped groups

To grant the Storage Admin (roles/storage.admin) role to all identities within the group GROUP_ID for project TEST_PROJECT_ID, run the following command:

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

Replace the following:

• TEST_PROJECT_ID: ID of the project
• WORKFORCE_POOL_ID: the workforce identity pool ID
• GROUP_ID: a group in the mapped google.groups claim.

Sign in and test access

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

Sign in

This section shows you how to sign in as a federated user and access Google 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

1. Enter user credentials in Microsoft Entra ID, if prompted.
Note: If you start an IdP-initiated sign-on, use the following URL for the Relay State parameter: https://console.cloud.google/.

gcloud CLI browser-based sign-in

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

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 using the --activate flag.

gcloud iam workforce-pools create-login-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID \
    --output-file=LOGIN_CONFIG_FILE

Replace the following:

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

The file contains 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.

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 with gcloud config set auth/login_config_file, the gcloud CLI uses your configuration file automatically:

  gcloud auth login

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

  gcloud auth login --login-config=LOGIN_CONFIG_FILE

• To use an environment variable to specify the location of the configuration file, set CLOUDSDK_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 with gcloud config set auth/login_config_file, you must run the following command to unset it:

  gcloud config unset auth/login_config_file

• Clear the CLOUDSDK_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 the following:

OIDC

1. Follow the steps in Send the sign-in request. Sign the user into your app with Microsoft Entra ID using OIDC.

2. Copy the ID token from the id_token parameter of the redirect URL and save it to a file in a secure location on your local machine. In a later step, you set PATH_TO_OIDC_ID_TOKEN to the path to this file.

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

   gcloud iam workforce-pools create-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 identity pool ID.
   • WORKFORCE_PROVIDER_ID: the workforce identity pool provider ID.
   • PATH_TO_OIDC_ID_TOKEN: the path to the file location where the IdP token is stored.
   • WORKFORCE_POOL_USER_PROJECT: the project number or ID used for quota and billing. The principal must have serviceusage.services.use permission on this project.

   When the command completes, the following config file is created by Microsoft 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:

   gcloud auth login --cred-file=PATH_TO_OIDC_CREDENTIALS
   

   Replace PATH_TO_OIDC_CREDENTIALS with the path to the output file from a previous step.

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

   You can now run gcloud CLI commands to Google Cloud.

SAML

1. Sign in a user to your Microsoft Entra ID app and get the SAML Response.

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

   SAML_ASSERTION_PATH=SAML_ASSERTION_PATH
   

3. To generate a configuration file like the example later in this step, run the following command:

   gcloud iam workforce-pools create-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 workforce identity pool provider ID you created earlier in this guide
   • WORKFORCE_POOL_ID: the workforce identity pool ID you created earlier in this guide
   • SAML_ASSERTION_PATH: the path of the SAML assertion file
   • PROJECT_ID: the project ID

   The configuration file that is generated looks similar to the following:

   {
     "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 gcloud using token exchange, run the following command:

   gcloud auth login --cred-file=config.json
   

   gcloud then transparently exchanges your Microsoft Entra ID credentials for temporary Google Cloud access tokens, allowing you to make other gcloud calls to 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:

   gcloud auth list
   

Test Access

You now have access to Google Cloud services that support Workforce Identity Federation and to which you are granted access. Earlier in this guide, you granted the Storage Admin role to all identities within a specific department for project TEST_PROJECT_ID. You can now test that you have access by listing Cloud Storage buckets.

Console (federated)

You can now execute gcloud CLI commands to Google Cloud.

• Go to Cloud Storage page.
• Verify that you can see list of existing buckets for the TEST_PROJECT_ID.

gcloud CLI

To list Cloud Storage buckets and objects for the project that you have access to, run the following command:

gcloud storage ls --project="TEST_PROJECT_ID"

The principal must have the serviceusage.services.use permission on the specified project.

Delete users

Workforce Identity Federation creates user metadata and resources for federated user identities. If you choose to delete users, in your IdP, for example, you must also explicitly delete these resources in Google Cloud. To do so, see Delete 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-running operation. After you initiate a deletion of a user's identity, processes that the user initiated before the deletion can continue to run until the processes complete or are canceled.

What's next

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