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
- Make sure that you have a Google Cloud organization set up.
-
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
- In Microsoft Entra ID, make sure that ID tokens are enabled for implicit flow. For more information, see Enable ID token implicit grant.
- For sign-in, your IdP must provide signed authentication information: OIDC IdPs must provide a JWT, and SAML IdP responses must be signed.
- 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.
- All groups that you intend to map must be marked as security groups in Microsoft Entra ID.
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:
Sign in to the Microsoft Entra administrator portal.
Go to Identity > Applications > App registrations.
To begin configuring the application registration, do the following:
Click New registration.
Enter a name for your application.
In Supported account types, select an option.
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
: 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.
To create the application registration, click Register.
SAML
To create a Microsoft Entra ID application registration that uses the SAML protocol, do the following:
Sign in to the Microsoft Entra administrator portal.
Go to Identity > Applications > App registrations.
To begin configuring the enterprise application, do the following:
Click New application > Create your own application.
Enter a name for your application.
Click Create.
Go to Single sign-on > SAML.
Update the Basic SAML Configuration as follows:
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.
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 IDWORKFORCE_PROVIDER_ID
: the workforce identity provider ID
To enable IdP-initiated sign-on, set the Relay State field to the following value:
https://console.cloud.google/
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:
-
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.
-
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
-
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:
- Go to API permissions.
- Click Add a Permission.
- Select Microsoft API.
- Select Application permissions.
- In the search field, type
User.ReadBasic.All
. - 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.
- 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.
- In the search field, enter
GroupMember.Read.All
. - Click Add permissions.
- Click Grant admin consent for your domain name.
- In the dialog that appears, click Yes.
- Go to the Overview page of the Microsoft Entra ID application that you created or updated earlier.
- 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 ishttps://login.microsoftonline.com/d41ad248-019e-49e5-b3de-4bdfe1fapple/v2.0/
. - In the search field, enter
Create a workforce identity pool
Console
To create the workforce identity pool, do the following:
In the Google Cloud console, go to the Workforce Identity Pools page:
Select the organization for your workforce identity pool. Workforce identity pools are available across all projects and folders in an organization.
Click Create pool and do the following:
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.
Optional: In Description, enter a description of the pool.
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).
To create the pool in the enabled state, make sure that Enabled Pool is on.
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).
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 prefixgcp-
is reserved and can't be used in a pool or provider ID. -
WORKFORCE_POOL_ID
: The workforce pool ID. -
DISPLAY_NAME
: A display name for the provider. -
ISSUER_URI
: The issuer URI from the Microsoft Entra ID application that you created earlier in this document. -
CLIENT_ID
: The client ID from your Microsoft Entra ID application. -
ATTRIBUTE_MAPPING
: The mapping of attributes from Microsoft Entra ID to Google Cloud. For example, to mapgroups
andsubject
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
: Useazure-ad-groups-mail
to retrieve the email addresses of the groups. Useazure-ad-groups-id
to retrieve the IDs of the groups. -
EXTRA_ATTRIBUTES_FILTER
: Optional. A filter expression that is used when querying the Microsoft Graph API for groups. You can use this parameter to ensure that the number of groups fetched from the IdP 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:
-
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.
-
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
-
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:
- Go to API permissions.
- Click Add a Permission.
- Select Microsoft API.
- Select Delegated permissions.
- In the search field, type
User.Read
. - 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.
- 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.
- In the search field, enter
GroupMember.Read.All
. - Click Add permissions.
- Click Grant admin consent for your domain name.
- In the dialog that appears, click Yes.
- Go to the Overview page of the Microsoft Entra ID application that you created or updated earlier.
- 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 ishttps://login.microsoftonline.com/d41ad248-019e-49e5-b3de-4bdfe1fapple/v2.0/
. - In the search field, enter
Create a workforce identity pool
Console
To create the workforce identity pool, do the following:
In the Google Cloud console, go to the Workforce Identity Pools page:
Select the organization for your workforce identity pool. Workforce identity pools are available across all projects and folders in an organization.
Click Create pool and do the following:
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.
Optional: In Description, enter a description of the pool.
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).
To create the pool in the enabled state, make sure that Enabled Pool is on.
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).
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 prefixgcp-
is reserved and can't be used in a pool or provider ID. -
WORKFORCE_POOL_ID
: The workforce pool ID. -
DISPLAY_NAME
: A display name for the provider. -
ISSUER_URI
: The issuer URI from the Microsoft Entra ID application that you created earlier in this document. -
CLIENT_ID
: The client ID from your Microsoft Entra ID application. -
ATTRIBUTE_MAPPING
: The mapping of attributes from Microsoft Entra ID to Google Cloud. For example, to mapgroups
andsubject
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
: Useazure-ad-groups-mail
to retrieve the email addresses of the groups. Useazure-ad-groups-id
to retrieve the IDs of the groups. -
EXTRA_ATTRIBUTES_FILTER
: Optional. A filter expression that is used when querying the Microsoft Graph API for groups. You can use this parameter to ensure that the number of groups fetched from the IdP 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:
-
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.
-
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
-
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:
- Go to API permissions.
- Click Add a Permission.
- Select Microsoft API.
- Select Application permissions.
- In the search field, type
User.ReadBasic.All
. - 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.
- 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.
- In the search field, enter
GroupMember.Read.All
. - Click Add permissions.
- Click Grant admin consent for your domain name.
- In the dialog that appears, click Yes.
- Go to the Overview page of the Microsoft Entra ID application that you created or updated earlier.
- 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 ishttps://login.microsoftonline.com/d41ad248-019e-49e5-b3de-4bdfe1fapple/v2.0/
. - In the search field, enter
Create a workforce identity pool
Console
To create the workforce identity pool, do the following:
In the Google Cloud console, go to the Workforce Identity Pools page:
Select the organization for your workforce identity pool. Workforce identity pools are available across all projects and folders in an organization.
Click Create pool and do the following:
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.
Optional: In Description, enter a description of the pool.
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).
To create the pool in the enabled state, make sure that Enabled Pool is on.
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).
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 prefixgcp-
is reserved and can't be used in a pool or provider ID. -
WORKFORCE_POOL_ID
: The workforce pool ID. -
DISPLAY_NAME
: A display name for the provider. -
XML_METADATA_PATH
: The path to the SAML 2.0 XML metadata file. -
ATTRIBUTE_MAPPING
: The mapping of attributes from Microsoft Entra ID to Google Cloud. For example, to mapgroups
andsubject
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
: Useazure-ad-groups-mail
to retrieve the email addresses of the groups. Useazure-ad-groups-id
to retrieve the IDs of the groups. -
EXTRA_ATTRIBUTES_FILTER
: Optional. A filter expression that is used when querying the Microsoft Graph API for groups. You can use this parameter to ensure that the number of groups fetched from the IdP 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:admin-group@altostrat.com
azure-ad-groups-id
: the group identifier is a UUID for the group—for example:abcdefgh-0123-0123-abcdef
Sign in and test access
In this section, you sign in as a workforce identity pool user and test that 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:
-
Go to the console (federated) sign-in page.
-
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 IDPROVIDER_ID
: the provider IDLOGIN_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", }
Sign in using browser-based authentication
To authenticate using browser-based sign-in authentication, you can use one of the following methods:
-
If you used the
--activate
flag when you created the configuration file, or if you activated the configuration file withgcloud config set auth/login_config_file
, the gcloud CLI uses your configuration file automatically: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 withgcloud 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
Follow the steps in Send the sign-in request. Sign the user into your application with Microsoft Entra ID using OIDC.
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.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 haveserviceusage.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" } }
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
Sign in a user to your Microsoft Entra ID application and get the SAML response.
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
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 guideWORKFORCE_POOL_ID
: the ID of the workforce identity pool that you created earlier in this guideSAML_ASSERTION_PATH
: the path of the SAML assertion filePROJECT_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" }
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
].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.
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)