Configure Workforce Identity Federation with Microsoft Entra ID and a large number of groups

This document shows you how to configure Workforce Identity Federation with the Microsoft Entra ID identity provider (IdP) and map up to 400 groups from Microsoft Entra ID to Google Cloud by using Microsoft Graph. The document then shows you how to grant IAM roles to those groups, and how to sign Microsoft Entra ID users that are members of the groups into Google Cloud. The users can then access Google Cloud products to which they were IAM granted access and which support Workforce Identity Federation.

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

You can use the method described in this document 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 can emit in a token is limited to 150 for SAML and 200 for JWT. To learn more about this limit, see Configure group claims for applications by using Microsoft Entra ID. To retrieve more groups, Workforce Identity Federation uses Microsoft Identity's OAuth 2.0 client credentials flow to obtain credentials that allow Workforce Identity Federation to query Microsoft Graph API and fetch a user's groups.

To use this method, at a high level, you do the following:

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

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

Workforce Identity Federation can retrieve a maximum of 999 groups from the Microsoft 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 can refine Workforce Identity Federation's query by using the --extra-attributes-filter flag, when you create the workforce identity pool provider.

After Workforce Identity Federation retrieves the groups from the Microsoft Graph API, it mints the access token. Workforce Identity Federation can add a maximum of 400 groups to the access token, so, to further filter the number of groups to 400 or fewer, you can specify an attribute mapping that contains common expression language (CEL) expressions, when you create the workforce identity pool provider.

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

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

This section shows you how to create a Microsoft Entra ID application using the Microsoft Entra admin portal. Alternatively, you can update your existing application. For additional details, see Establish 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 OIDC protocol, do the following:

1. Sign in to the Microsoft Entra administrator portal.

2. Go to Identity > Applications > App registrations.

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

   1. Click New registration.

   2. Enter a name for your application.

   3. In Supported account types, select an option.

   4. In the Redirect URI section, in the Select a platform drop-down list, select Web.

   5. 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: a workforce identity pool ID that you will use when creating the workforce identity pool later in this document—for example: entra-id-oidc-pool

      • WORKFORCE_PROVIDER_ID: a workforce identity pool provider ID that you will use when you create the workforce identity pool provider later in this document—for example: entra-id-oidc-pool-provider

        For information on formatting the ID, see the Query parameters section in the API documentation.

   6. To create the application registration, click Register.

SAML

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

1. Sign in to the Microsoft Entra administrator portal.

2. Go to Identity > Applications > App registrations.

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

   1. Click New application > Create your own application.

   2. Enter a name for your application.

   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
         

         Replace the following:

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

         • WORKFORCE_PROVIDER_ID: a workforce identity pool provider ID that you will use when you create the workforce identity pool provider later in this document—for example: entra-id-saml-pool-provider

           For information on formatting the ID, see the Query parameters section in the API documentation.

      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 workforce identity pool ID
         • WORKFORCE_PROVIDER_ID: the workforce identity provider ID

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

         https://console.cloud.google/
         

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

Configure large numbers of groups with Microsoft Entra ID

This section describes how to map up to 400 groups from Microsoft Entra ID to Workforce Identity Federation using the OIDC and SAML protocols.

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

This section describes how to map up to 400 groups from Microsoft 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 in Register a new application.
   • To update an existing application, do the following:
     • Go to Identity > Applications > Enterprise applications.
     • Select the application that you want to update.
2. Create a new client secret in the application by following the instructions in Certificates & 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 Workload 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 to API permissions.
   2. Click Add a Permission.
   3. Select Microsoft API.
   4. Select Application permissions.
   5. In the search field, type User.ReadBasic.All.
   6. Click Add 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, enter GroupMember.Read.All.
   2. Click Add permissions.
   3. Click Grant admin consent for your domain name.
   4. In the dialog that appears, click Yes.
   5. Go to the Overview page of the Microsoft Entra ID application that you created or updated earlier.
   6. Click Endpoints.

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

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

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. Select the organization for your workforce identity pool. Workforce identity pools are available across all projects and folders in an organization.

3. 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 for the workforce identity pool. Workforce identity pools are available across all projects and folders in the 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.

Configure the OIDC implicit flow workforce identity pool provider

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

gcloud iam workforce-pools providers create-oidc PROVIDER_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

Replace the following:

• PROVIDER_ID: A unique provider ID. The prefix gcp- 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 map groups and subject from Microsoft Entra ID, use the following attribute mapping:

  --attribute-mapping=”google.groups=assertion.groups, google.subject=assertion.sub"

  For more information, see Attribute 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: Use azure-ad-groups-mail to retrieve the email addresses of the groups. Use azure-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 remain below the limit of 999 groups.

  The following example fetches the groups which have the prefix sales in their email id:

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

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

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

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

This section describes how to map up to 400 groups from Microsoft Entra ID to Workforce Identity Federation using the OIDC protocol with 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 in Register a new application.
   • To update an existing application, do the following:
     • Go to Identity > Applications > Enterprise applications.
     • Select the application that you want to update.
2. Create a new client secret in the application by following the instructions in Certificates & 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 Workload 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 to API permissions.
   2. Click Add a Permission.
   3. Select Microsoft API.
   4. Select Delegated permissions.
   5. In the search field, type User.Read.
   6. Click Add 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, enter GroupMember.Read.All.
   2. Click Add permissions.
   3. Click Grant admin consent for your domain name.
   4. In the dialog that appears, click Yes.
   5. Go to the Overview page of the Microsoft Entra ID application that you created or updated earlier.
   6. Click Endpoints.

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

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

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. Select the organization for your workforce identity pool. Workforce identity pools are available across all projects and folders in an organization.

3. 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 for the workforce identity pool. Workforce identity pools are available across all projects and folders in the 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.

Configure the OIDC code flow workforce identity pool provider

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

gcloud iam workforce-pools providers create-oidc PROVIDER_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=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

Replace the following:

• PROVIDER_ID: A unique provider ID. The prefix gcp- 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 map groups and subject from Microsoft Entra ID, use the following attribute mapping:

  --attribute-mapping=”google.groups=assertion.groups, google.subject=assertion.sub"

  For more information, see Attribute 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: Use azure-ad-groups-mail to retrieve the email addresses of the groups. Use azure-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 remain below the limit of 999 groups.

  The following example fetches the groups which have the prefix sales in their email id:

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

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

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

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

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

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 in Register a new application.
   • To update an existing application, do the following:
     • Go to Identity > Applications > Enterprise applications.
     • Select the application that you want to update.
2. Create a new client secret in the application by following the instructions in Certificates & 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 Workload 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 to API permissions.
   2. Click Add a Permission.
   3. Select Microsoft API.
   4. Select Application permissions.
   5. In the search field, type User.ReadBasic.All.
   6. Click Add 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, enter GroupMember.Read.All.
   2. Click Add permissions.
   3. Click Grant admin consent for your domain name.
   4. In the dialog that appears, click Yes.
   5. Go to the Overview page of the Microsoft Entra ID application that you created or updated earlier.
   6. Click Endpoints.

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

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

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. Select the organization for your workforce identity pool. Workforce identity pools are available across all projects and folders in an organization.

3. 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 for the workforce identity pool. Workforce identity pools are available across all projects and folders in the 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.

Configure the SAML 2.0 workforce identity pool provider

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

gcloud iam workforce-pools providers create-saml PROVIDER_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

Replace the following:

• PROVIDER_ID: A unique provider ID. The prefix gcp- 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 map groups and subject from Microsoft Entra ID, use the following attribute mapping:

  --attribute-mapping=”google.groups=assertion.groups, google.subject=assertion.sub"

  For more information, see Attribute 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: Use azure-ad-groups-mail to retrieve the email addresses of the groups. Use azure-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 remain below the limit of 999 groups.

  The following example fetches the groups which have the prefix sales in their email id:

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

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

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

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, see Represent 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-binding PROJECT_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: [e-mail]
  • 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 you have access to Google Cloud resources.

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

If prompted, enter user credentials in Microsoft Entra ID.

If you start an IdP-initiated sign-on, use the following for the relay 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 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 adding the --activate flag. You can then run gcloud auth login without specifying the configuration file path each time.

gcloud iam workforce-pools create-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 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://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_PATH

• 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 application 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 application 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 credential configuration file, 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 ID of the workforce identity pool provider that you created earlier in this guide
   • WORKFORCE_POOL_ID: the ID of the workforce identity pool that 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 the gcloud CLI using Workforce Identity Federation token exchange, run the following command:

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

   The gcloud CLI then transparently exchanges your Microsoft Entra 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:

   gcloud auth list
   

Test Access

You now have access to the Google Cloud products that support Workforce Identity Federation and to which you are granted access. Earlier in this document, you granted the Storage Admin role (roles/storage.admin) to all of the identities within the group identifier that you specified in the gcloud projects add-iam-policy-binding for project TEST_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 the following:

• Go to the Cloud Storage page.

  Go to Cloud Storage

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

gcloud CLI

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

gcloud storage ls --project="TEST_PROJECT_ID"

Delete users

Workforce Identity Federation creates user metadata and resources for federated user identities. If you choose to delete users in your IdP 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)