Skip to main content
Send feedback
Configure Workforce Identity Federation with Microsoft Entra ID and sign in users
Stay organized with collections
Save and categorize content based on your preferences.
This document shows you how to configure Workforce Identity Federation with
the Microsoft Entra ID identity provider (IdP) and manage access to
Google Cloud. Federated users can then access Google Cloud services
that support Workforce Identity Federation .
You can use either the OIDC protocol or SAML 2.0 protocol to federate
identities.
Before you begin
Make sure that you have a Google Cloud organization set up.
Install the Google Cloud CLI.
After installation,
initialize the Google Cloud CLI by running the following command:
gcloud init
If you're using an external identity provider (IdP), you must first
sign in to the gcloud CLI with your federated identity .
Note: If you installed the gcloud CLI previously, make sure you have
the latest version by running gcloud components update.
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 .
Costs
Workforce Identity Federation is available
as a no-cost feature. However, Workforce Identity Federation detailed audit logging uses Cloud Logging. To learn about Logging pricing,
see Google Cloud Observability pricing .
Required roles
To get the permissions that
you need to configure Workforce Identity Federation,
ask your administrator to grant you the
IAM Workforce Pool Admin (roles/iam.workforcePoolAdmin) IAM role on the organization.
For more information about granting roles, see Manage access to projects, folders, and organizations .
You might also be able to get
the required permissions through custom
roles or other predefined
roles .
If you're configuring permissions in a development or test environment—but not a
production environment—you can grant the IAM Owner
(roles/owner) basic role, which also includes permissions for
Workforce Identity Federation.
Create a Microsoft Entra ID application
This section shows you how to create a Microsoft Entra ID application using the
Microsoft Entra admin center. 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 admin center.
Go to Entra ID > 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 entra-id-oidc-pool.WORKFORCE_PROVIDER_ID 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 .
To use the example attribute mapping that is
provided later in this document, you must create a custom department attribute.
Recommended: As a security best practice , we
recommend that you configure a group claim by doing the following:
Go to your Microsoft Entra ID application registration.
Click Token configuration .
Click Add groups claim .
Select the group types to return. For more details, refer to Configuring groups optional claims .
SAML To create a Microsoft Entra ID application registration that uses the SAML
protocol, do the following:
Sign in to the Microsoft Entra admin center.
Go to Entra ID > Enterprise applications .
To begin configuring the enterprise application, do the following:
Click New application > Create your own application .
In the Create your own application pane that appears, 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 entra-id-saml-pool.WORKFORCE_PROVIDER_ID 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 WORKFORCE_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 .
To use the example attribute mapping that is
provided later in this document, you must create a custom department attribute.
Assign users or groups to the application .
Recommended: As a security best practice , we
recommend that you configure a group claim by doing the following:
Go to your Microsoft Entra ID application.
Click Single sign-on .
In the Attributes & Claims section, click Edit .
Click Add a group claim .
Select the group type to return. For more details, refer to Add group claims to tokens for SAML applications using SSO configuration .
Create a workforce identity pool
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 Query parameters
section in the API documentation.ORGANIZATION_ID DISPLAY_NAME DESCRIPTION SESSION_DURATION s—for example, 3600s. 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. Session duration defaults to one hour (3600s). The
session duration value must be between 15 minutes (900s) and 12 hours
(43200s).
Tip: Run gcloud iam workforce-pools create --help to find other
parameters you can customize for this command. Console To create the workforce identity pool, do the following:
In the Google Cloud console, go to the Workforce Identity Pools
page:
Go to Workforce Identity Pools
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.
To create the workforce identity pool, click Next .
The workforce identity pool's session duration defaults to one hour (3600s).
The session duration determines how long the Google Cloud access tokens,
console (federated) ,
and gcloud CLI sign-in sessions from this workforce pool
are valid. After you create the pool, you can update the pool to set
a custom session duration. The session duration must be from 15
minutes (900s) to 12 hours (43200s).
Create the Microsoft Entra ID workforce identity pool provider
This section describes how to create a
workforce identity pool provider
to enable your IdP users to access Google Cloud. You can configure the provider to use either the OIDC or SAML protocol.
Create an OIDC workforce identity pool provider
To create a workforce identity pool provider for your Microsoft Entra ID
application integration, using the OIDC protocol, do the following:
To get the issuer URI for your Microsoft Entra ID application, do the
following:
Go to the Overview page of your Microsoft Entra ID application
registration.
Click Endpoints .
Find the OpenID Connect metadata document endpoint. The issuer URI
is the OpenID Connect metadata document URI, omitting the trailing
/.well-known/openid-configuration.
For example, if the OpenID Connect metadata document URI 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/.
Alternatively, you can copy the OpenID Connect metadata document
URL, open it in a browser tab, and copy the value of issuer from the
JSON response.
To get the client ID for your Microsoft Entra ID application, do the
following:
Go to the Overview page of your Microsoft Entra ID application
registration.
In Application (client) ID , copy the value.
To create an OIDC workforce identity pool provider for web-based
sign-in, do the following:
gcloud To create a provider that supports the OIDC protocol, do the following:
Code flow To create an OIDC provider that uses authorization code flow for web-based sign-in,
do the following:
In your Microsoft Entra ID application, to get your client secret,
do the following:
Go to your Microsoft Entra ID app registration.
In Certificates & secrets , click the Client secrets tab.
To add a client secret, click + New client secret .
In the Add a client secret dialog, enter information, as needed.
To create the client secret, click Add .
In the Client secrets tab, find your new client secret.
In the Value column for your new client secret, click
content_copy Copy .
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 " \OIDC_CLIENT_SECRET " \
--web-sso-response-type="code" \
--web-sso-assertion-claims-behavior="merge-user-info-over-id-token-claims" \
--web-sso-additional-scopes="WEB_SSO_ADDITIONAL_SCOPES " \
--attribute-mapping="ATTRIBUTE_MAPPING " \
--attribute-condition="ATTRIBUTE_CONDITION " \
--jwk-json-path="JWK_JSON_PATH " \
--detailed-audit-logging \
--location=global
Replace the following:
WORKFORCE_PROVIDER_ID gcp- is reserved and can't be used in a workforce identity pool or workforce identity pool provider ID.WORKFORCE_POOL_ID DISPLAY_NAME idp-eu-employees.DESCRIPTION IdP for Partner Example Organization employees.
ISSUER_URI https; for example,
https://example.com/oidc. Note: For security reasons, ISSUER_URI OIDC_CLIENT_ID aud claim
of the JWT that is issued by your IdP.OIDC_CLIENT_SECRET WEB_SSO_ADDITIONAL_SCOPES ATTRIBUTE_MAPPING attribute mapping .
For Microsoft Entra ID with OIDC authentication, we recommend the following
attribute mappings:
google.subject=assertion.oid,
google.groups=assertion.groups,
google.display_name=assertion.preferred_username
This example maps the IdP attributes assertion.oid,
assertion.groups, and
assertion.preferred_username to the Google Cloud
attributes google.subject, google.groups,
and google.display_name, respectively.
ATTRIBUTE_CONDITION attribute condition ;
for example, to limit the ipaddr attribute to a
certain IP range you can set the condition assertion.ipaddr.startsWith('98.11.12.')
.
JWK_JSON_PATH 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.
You can't use local OIDC JWKs when signing in to the console (federated).
Workforce Identity Federation detailed audit logging logs information received from your IdP to Logging. Detailed audit logging can help you troubleshoot your workforce identity pool provider configuration. To learn how to troubleshoot attribute mapping errors with detailed audit logging, see General attribute mapping errors . To learn about Logging pricing, see
Google Cloud Observability pricing .
To disable detailed audit logging for a workforce identity pool provider, omit the --detailed-audit-logging flag when you run gcloud iam workforce-pools providers create. To disable detailed audit logging, you can also update the provider .
In the command response, POOL_RESOURCE_NAME is the name of the pool;
for example, locations/global/workforcePools/enterprise-example-organization-employees.
Implicit flow To create an OIDC provider that uses the implicit flow
for web sign-in, do the following:
To enable the ID token in your Microsoft Entra ID application, do
the following:
Go to your Microsoft Entra ID application registration.
In Authentication , select the ID token checkbox.
Click Save .
To create the provider, run the following command:
gcloud iam workforce-pools providers create-oidc WORKFORCE_PROVIDER_ID \
--workforce-pool=WORKFORCE_POOL_ID \
--display-name="DISPLAY_NAME " \
--description="DESCRIPTION " \
--issuer-uri="ISSUER_URI " \
--client-id="OIDC_CLIENT_ID " \
--web-sso-response-type="id-token" \
--web-sso-assertion-claims-behavior="only-id-token-claims" \
--web-sso-additional-scopes="WEB_SSO_ADDITIONAL_SCOPES " \
--attribute-mapping="ATTRIBUTE_MAPPING " \
--attribute-condition="ATTRIBUTE_CONDITION " \
--jwk-json-path="JWK_JSON_PATH " \
--detailed-audit-logging \
--location=global
Replace the following:
WORKFORCE_PROVIDER_ID gcp- is reserved and can't be used in a workforce identity pool or workforce identity pool provider ID.WORKFORCE_POOL_ID DISPLAY_NAME idp-eu-employees.DESCRIPTION IdP for Partner Example Organization employees.
ISSUER_URI https; for example,
https://example.com/oidc. Note: For security reasons, ISSUER_URI OIDC_CLIENT_ID aud claim
of the JWT that is issued by your IdP.WEB_SSO_ADDITIONAL_SCOPES ATTRIBUTE_MAPPING attribute mapping .
For Microsoft Entra ID with OIDC authentication, we recommend the following
attribute mappings:
google.subject=assertion.oid,
google.groups=assertion.groups,
google.display_name=assertion.preferred_username
This example maps the IdP attributes assertion.oid,
assertion.groups, and
assertion.preferred_username to the Google Cloud
attributes google.subject, google.groups,
and google.display_name, respectively.
ATTRIBUTE_CONDITION attribute condition ;
for example, to limit the ipaddr attribute to a
certain IP range you can set the condition assertion.ipaddr.startsWith('98.11.12.')
.
JWK_JSON_PATH 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.
You can't use local OIDC JWKs when signing in to the console (federated).
Workforce Identity Federation detailed audit logging logs information received from your IdP to Logging. Detailed audit logging can help you troubleshoot your workforce identity pool provider configuration. To learn how to troubleshoot attribute mapping errors with detailed audit logging, see General attribute mapping errors . To learn about Logging pricing, see
Google Cloud Observability pricing .
To disable detailed audit logging for a workforce identity pool provider, omit the --detailed-audit-logging flag when you run gcloud iam workforce-pools providers create. To disable detailed audit logging, you can also update the provider .
In the command response, POOL_RESOURCE_NAME is the name of the pool;
for example, locations/global/workforcePools/enterprise-example-organization-employees.
Console
Code flow To create an OIDC provider that uses authorization code flow
for web-based sign-in, do the following:
To get the Microsoft Entra ID client secret, do the following:
Go to your Microsoft Entra ID app registration.
In Certificates & secrets , click the Client secrets tab.
To add a client secret, click + New client secret .
In the Add a client secret dialog, enter information, as needed.
To create the client secret, click Add .
In the Client secrets tab, find your new client secret.
In the Value column for your new client secret, click
content_copy Copy .
In the Google Cloud console, go to the Workforce Identity Pools page:
Go to Workforce Identity Pools
In the Workforce Identity Pools table, select the pool for which you want to create the provider.
In the Providers section, click add Add Provider
In the Select a Provider vendor list, select your IdP.
If your IdP isn't listed, then select Generic Identity Provider .
In Select an authentication protocol , select OpenID Connect (OIDC) .
In the Create a provider section, do the following:
In Name , enter the name for the provider.
In Description , enter the description for the provider.
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.
In Client ID , enter the OIDC client ID that is registered
with your OIDC IdP; the ID must match the aud claim of the JWT that is
issued by your IdP.
To create a provider that is enabled, make sure Enable provider is on.
Click Continue .
In the Share your provider information with IdP section, copy the URL. In your IdP, configure this URL as the redirect URI, which informs your IdP where to send the assertion token after logging in.
Click Continue .
In the Configure OIDC Web Sign-in section, do the following:
In the Flow type list, select Code .
In the Assertion claims behavior list, select either of the following:
User info and ID token Only ID token
In the Client secret field, enter the client secret from your IdP.
Click Continue .
In the Configure provider section, for
Detailed logging , click the
Enable attribute value audit logging toggle.
Workforce Identity Federation detailed audit logging logs information received from your IdP to Logging. Detailed audit logging can help you troubleshoot your workforce identity pool provider configuration. To learn how to troubleshoot attribute mapping errors with detailed audit logging, see General attribute mapping errors . To learn about Logging pricing, see
Google Cloud Observability pricing .
To disable detailed audit logging for a workforce identity pool provider, leave the Enable attribute value audit logging toggle off when you create the provider. To disable detailed audit logging, you can also update the provider .
To create the provider, click Submit .
After the provider is created, you are redirected to the provider
attributes page.
To configure attribute mappings and conditions, do the
following:
When prompted, sign in to your external IdP to validate the default
attribute mappings.
On the provider attributes page, view and edit the attribute
mappings and conditions:
To add or edit attribute mappings, do the following:
Click Add mapping to add a new mapping, or edit the
existing mappings.
In the Google n field, where n is a number,
select a Google Cloud-supported key.
In the corresponding OIDC n field, enter the
IdP attribute name or a CEL expression.
For Microsoft Entra ID with OIDC authentication, we recommend the following
attribute mappings:
google.subject=assertion.oid,
google.groups=assertion.groups,
google.display_name=assertion.preferred_username
This example maps the IdP attributes assertion.oid,
assertion.groups, and
assertion.preferred_username to the Google Cloud
attributes google.subject, google.groups,
and google.display_name, respectively.
To increase the number of groups, do the following:
Click Enable for extra attributes.
In the subtask that opens, enter the following details:
In the Extra Attributes Issuer URI field,
enter the issuer URL.
In the Extra Attributes Client ID field,
enter the client ID.
In the Extra Attributes Client Secret field,
enter the client secret.
In the Extra Attributes Type list, select
an attribute type for extra attributes.
In the Extra Attributes Filter field, enter a
filter expression to be used when querying the Microsoft
Graph API for groups.
Click Enable .
After you enable extra attributes, you can click Edit to
reopen the subtask and edit the details, or click Disable
to turn off extra attributes.
To add an attribute condition, do the following:
Click Add condition .
In the Attribute Conditions field, enter a
condition in CEL format ; for example,
to limit the ipaddr attribute to a
certain IP range you can set the condition assertion.ipaddr.startsWith('98.11.12.')
.
To validate your mappings, click Save and refetch token .
To complete the setup, click Save and exit .
Implicit flow To create an OIDC provider that uses implicit flow
for web-based sign-in, do the following:
To enable the ID token in your Microsoft Entra ID application, do
the following:
Go to your Microsoft Entra ID application registration.
In Authentication , select the ID token checkbox.
Click Save .
In the Google Cloud console, go to the Workforce Identity Pools page:
Go to Workforce Identity Pools
In the Workforce Identity Pools table, select the pool for which you want to create the provider.
In the Providers section, click add Add Provider
In the Select a Provider vendor list, select your IdP.
If your IdP isn't listed, then select Generic Identity Provider .
In Select an authentication protocol , select OpenID Connect (OIDC) .
In the Create a provider section, do the following:
In Name , enter the name for the provider.
In Description , enter the description for the provider.
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.
In Client ID , enter the OIDC client ID that is registered
with your OIDC IdP; the ID must match the aud claim of the JWT that is
issued by your IdP.
To create a provider that is enabled, make sure Enable provider is on.
Click Continue .
In the Share your provider information with IdP section, copy the URL. In your IdP, configure this url as the redirect URI, which informs your IdP where to send the assertion token after logging in.
Click Continue .
In the Configure OIDC Web Sign-in section, do the following:
In the Flow type list, select ID Token .
In the Assertion claims behavior list, ID token is selected.
Click Continue .
In the Configure provider section, in
Detailed logging , click the
Enable attribute value audit logging toggle.
Workforce Identity Federation detailed audit logging logs information received from your IdP to Logging. Detailed audit logging can help you troubleshoot your workforce identity pool provider configuration. To learn how to troubleshoot attribute mapping errors with detailed audit logging, see General attribute mapping errors . To learn about Logging pricing, see
Google Cloud Observability pricing .
To disable detailed audit logging for a workforce identity pool provider, leave the Enable attribute value audit logging toggle off when you create the provider. To disable detailed audit logging, you can also update the provider .
To create the provider, click Submit .
After the provider is created, you are redirected to the provider
attributes page.
To configure attribute mappings and conditions, do the
following:
When prompted, sign in to your external IdP to validate the default
attribute mappings.
On the provider attributes page, view and edit the attribute
mappings and conditions:
To add or edit attribute mappings, do the following:
Click Add mapping to add a new mapping, or edit the
existing mappings.
In the Google n field, where n is a number,
select a Google Cloud-supported key.
In the corresponding OIDC n field, enter the
IdP attribute name or a CEL expression.
For Microsoft Entra ID with OIDC authentication, we recommend the following
attribute mappings:
google.subject=assertion.oid,
google.groups=assertion.groups,
google.display_name=assertion.preferred_username
This example maps the IdP attributes assertion.oid,
assertion.groups, and
assertion.preferred_username to the Google Cloud
attributes google.subject, google.groups,
and google.display_name, respectively.
To increase the number of groups, do the following:
Click Enable for extra attributes.
In the subtask that opens, enter the details:
In the Extra Attributes Issuer URI field,
enter the issuer URL.
In the Extra Attributes Client ID field,
enter the client ID.
In the Extra Attributes Client Secret field,
enter the client secret.
In the Extra Attributes Type list, select
an attribute type for extra attributes.
In the Extra Attributes Filter field, enter a
filter expression to be used when querying the Microsoft
Graph API for groups.
Click Enable .
After you enable extra attributes, you can click Edit to
reopen the subtask and edit the details, or click Disable
to turn off extra attributes.
To add an attribute condition, do the following:
Click Add condition .
In the Attribute Conditions field, enter a
condition in CEL format ; for example,
to limit the ipaddr attribute to a
certain IP range you can set the condition assertion.ipaddr.startsWith('98.11.12.')
.
To validate your mappings, click Save and refetch token .
To complete the setup, click Save and exit .
Create a SAML 2.0 workforce identity pool provider
In your SAML IdP, register a new application for Google Cloud
Workforce Identity Federation.
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
Set the redirect URL, also known as the Assertion Consumer Service
(ACS) URL. To set the redirect URL, locate the redirect URL field in your
SAML IdP, and do one of the following:
To set up browser-based sign-in through the Google Cloud console or
another browser-based sign-in method, enter following URL:
https://auth.cloud.google/signin-callback/locations/global/workforcePools/WORKFORCE_POOL_ID /providers/WORKFORCE_PROVIDER_ID
Replace the following:
To set up programmatic sign-in through your IdP, enter the following URL:
localhost
See Set up user access to the console
for more details on configuring console sign-in.
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.
gcloud To save the SAML metadata for your Microsoft Entra ID application and
create the provider, do the following:
Go to your Microsoft Entra ID application.
Click Single sign-on .
In the SAML Certificates section, download the
Federation Metadata XML .
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 " \
--detailed-audit-logging \
--location= global
Replace the following:
WORKFORCE_PROVIDER_ID WORKFORCE_POOL_ID DISPLAY_NAME DESCRIPTION XML_METADATA_PATH ATTRIBUTE_MAPPING attribute
mapping —
for example:
google.subject=assertion.attributes['http://schemas.microsoft.com/identity/claims/objectidentifier'],
attribute.costcenter=assertion.attributes.costcenter[0]This example maps the assertion.attributes['http://schemas.microsoft.com/identity/claims/objectidentifier']
IdP attribute to google.subject and the assertion.attributes.costcenter[0]
IdP attribute to attribute.costcenter.
For more information, see Attribute mapping .
ATTRIBUTE_CONDITION 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.
Workforce Identity Federation detailed audit logging logs information received from your IdP to Logging. Detailed audit logging can help you troubleshoot your workforce identity pool provider configuration. To learn how to troubleshoot attribute mapping errors with detailed audit logging, see General attribute mapping errors . To learn about Logging pricing, see
Google Cloud Observability pricing .
To disable detailed audit logging for a workforce identity pool provider, omit the --detailed-audit-logging flag when you run gcloud iam workforce-pools providers create. To disable detailed audit logging, you can also update the provider .
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 WORKFORCE_POOL_ID WORKFORCE_PROVIDER_ID
KEY_SPECIFICATION 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 WORKFORCE_POOL_ID WORKFORCE_PROVIDER_ID CERTIFICATE_PATH saml-certificate.cer or saml-certificate.pem
To configure Microsoft Entra ID to encrypt SAML tokens, see
<a
href="https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/howto-saml-token-encryption?tabs=azure-portal"
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 WORKFORCE_POOL_ID WORKFORCE_PROVIDER_ID
Supported SAML encryption algorithms
Workforce identity federation supports the following key transport algorithms:
Workforce identity federation supports the following block encryption algorithms:
Console
To configure the SAML provider using the Google Cloud console, do the following:
In the Google Cloud console, go to the Workforce Identity Pools page:
Go to Workforce Identity Pools
In the Workforce Identity Pools table, select the pool for which you want to create the provider.
In the Providers section, click add Add Provider
In the Select a Provider vendor list, select your IdP.
If your IdP isn't listed, then select Generic Identity Provider .
In Select an authentication protocol , select SAML .
In the Create a provider section, do the following:
In Name , enter a name for the provider.
Optional: In Description , enter a description for the provider.
In IDP metadata file (XML) , select the metadata XML file that you generated earlier in this guide.
To create a provider that is enabled, make sure Enable provider is on.
Click Continue .
In the Share your provider information section, copy the URLs. In
your IdP, configure the first URL as the entity ID, which identifies your
application to the IdP. Configure the other URL as the redirect URI, which
informs your IdP where to send the assertion token after signing in.
Click Continue .
In the Configure provider section, in Detailed logging ,
click the Enable attribute value audit logging toggle.
Workforce Identity Federation detailed audit logging logs information received from your IdP to Logging. Detailed audit logging can help you troubleshoot your workforce identity pool provider configuration. To learn how to troubleshoot attribute mapping errors with detailed audit logging, see General attribute mapping errors . To learn about Logging pricing, see
Google Cloud Observability pricing .
To disable detailed audit logging for a workforce identity pool provider, leave the Enable attribute value audit logging toggle off when you create the provider. To disable detailed audit logging, you can also update the provider .
To create the provider, click Submit .
After the provider is created, you are redirected to the provider
attributes page.
To configure attribute mappings and conditions, do the
following:
When prompted, sign in to your external IdP to validate the default
attribute mappings.
On the provider attributes page, view and edit the attribute mappings
and conditions:
To add or edit attribute mappings, do the following:
Click Add mapping to add a new mapping, or edit
the existing mappings.
In the Google n field, where n is a number,
select a Google Cloud supported key.
In the corresponding SAML n field,
enter the IdP attribute name or a CEL
expression—for example:
google.subject=assertion.attributes['http://schemas.microsoft.com/identity/claims/objectidentifier'],
attribute.costcenter=assertion.attributes.costcenter[0] This example maps the assertion.attributes['http://schemas.microsoft.com/identity/claims/objectidentifier']
IdP attribute to google.subject and the assertion.attributes.costcenter[0]
IdP attribute to attribute.costcenter.
To increase the number of groups, do the following:
Click Enable for extra attributes.
In the subtask that opens, enter the details:
In the Extra Attributes Issuer URI field,
enter the issuer URL.
In the Extra Attributes Client ID field,
enter the client ID.
In the Extra Attributes Client Secret field,
enter the client secret.
In the Extra Attributes Type list, select
an attribute type for extra attributes.
In the Extra Attributes Filter field, enter a
filter expression to be used when querying the Microsoft
Graph API for groups.
Click Enable .
After you enable extra attributes, you can click Edit
to reopen the subtask and edit the details, or click
Disable to turn off extra attributes.
To add an attribute condition, do the following:
Click Add condition .
In the Attribute Conditions field, enter a
condition in CEL format —for example,
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..
To validate your mappings, click Save and refetch token .
To complete the setup, click Save and exit .
Verify your provider configuration
Before testing the end-user sign-in flow, you can verify that your provider configuration is correct and that Google Cloud can exchange tokens with your IdP.
The Validate your provider attributes page in the Google Cloud console includes an attributes viewer that lets you
interactively test your configuration and debug Common Expression
Language (CEL) expressions. You can use the attributes viewer to do
the following:
View the raw attributes sent in the IdP assertion.
Verify that your attribute mappings and conditions correctly transform
those attributes.
Debug complex CEL expressions in real time.
To verify your provider configuration, do the following:
To enable the browser-based sign-in flow for Workforce Identity Federation, add https://auth.cloud.google/signin-callback/locations/global/workforcePools/POOL_ID /providers/PROVIDER_ID to your IdP's list of allowed redirect URIs.
In the Google Cloud console, go to Workforce Identity Pools .
Go to Workforce Identity Pools
From the list of pools, click the name of the pool you want to verify.
In the Workforce pool details page, click the name of the IdP you want
to verify.
In the Provider Details page, click Debug IdP token .
In the Sign in dialog, sign in to your IdP as a test user.
The Validate your provider attributes page displays the mapped attributes
and the result of your attribute condition.
The Mapped attributes from your IdP token section displays how Google attributes, such as
google.subject, are populated from your IdP's token based on your
mapping configuration. An error icon appears if a mapping is incorrect.
The Attribute condition section shows the boolean result of your
condition. If the condition evaluates to false, the sign-in is
blocked.
To view the full assertion token, click View full token . This shows the raw JSON object from your IdP. Reference a
top-level property in your mappings using the format
assertion.PROPERTY_NAME.
Edit your provider configuration
To correct any errors, you can edit the configuration:
In the Validate your provider attributes page, click
edit
Edit .
Make the necessary changes.
To start a new test and see the updated results, click Save and refetch token .
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
Workforce principal identifiers for allow policies .
Using mapped groups To grant the Storage Admin role (roles/storage.admin) to all identities
within the group GROUP_ID TEST_PROJECT_ID
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 WORKFORCE_POOL_ID GROUP_ID google.groups claim. For single identity To grant the Storage Admin (roles/storage.admin) role to a single identity
for project TEST_PROJECT_ID
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 WORKFORCE_POOL_ID SUBJECT_VALUE Using mapped department attribute To grant the Storage Admin role (roles/storage.admin) to all identities
within a specific department for project
TEST_PROJECT_ID
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 WORKFORCE_POOL_ID DEPARTMENT_VALUE attribute.department value 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.
Go to console (federated)
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
Run the following command to create a login configuration file:
Linux and macOS
gcloud iam workforce-pools create-login-config \
locations/global/workforcePools/WORKFORCE_POOL_ID /providers/WORKFORCE_PROVIDER_ID \
--output-file= LOGIN_CONFIG_PATH
Windows (PowerShell)
gcloud iam workforce-pools create-login-config `
locations/global/workforcePools/WORKFORCE_POOL_ID /providers/WORKFORCE_PROVIDER_ID `
--output-file= LOGIN_CONFIG_PATH
Note: You can optionally activate the login configuration file as the default for the
gcloud CLI by adding the
--activate flag. You can then run gcloud auth login to authorize
the gcloud CLI without specifying the login configuration file path each time.
Replace the following:
WORKFORCE_POOL_ID WORKFORCE_PROVIDER_ID
LOGIN_CONFIG_PATH login-config.json.
The login configuration file contains the endpoints used by the gcloud CLI to enable
the browser-based authentication flow and set the audience to the IdP that was configured in the
workforce identity pool provider. The file doesn't contain confidential information.
The login configuration file content looks similar to the following:
{
"universe_domain" : "googleapis.com" ,
"universe_cloud_web_domain" : "cloud.google" ,
"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
Point to the login configuration file with an environment variable, a property in the active
gcloud CLI configuration, or use it directly with the gcloud auth login
command:
Environment variable
To use the login configuration file with an environment variable, complete the following
instructions:
Set the CLOUDSDK_AUTH_LOGIN_CONFIG_FILE environment variable to the path of
the login configuration file.
Run the following command:
gcloud auth login
The gcloud CLI references the environment variable to find the login
configuration file, and then starts the authentication process. Follow the browser-based
flow to authenticate and authorize the gcloud CLI to access resources on your behalf for
future commands.
To stop using the login configuration file for gcloud auth login commands, clear
the CLOUDSDK_AUTH_LOGIN_CONFIG_FILE environment variable.
gcloud CLI configuration
To use the login configuration file with a gcloud CLI configuration property,
complete the following instructions:
Set the active gcloud CLI configuration's auth/login_config_file property to
the login configuration file's path with the following command:
gcloud config set auth/login_config_file LOGIN_CONFIG_PATH
Run the following command:
gcloud auth login
The gcloud CLI references the configuration property to find the login
configuration file, and then starts the authentication process. Follow the browser-based
flow to authenticate and authorize the gcloud CLI to access resources on your behalf for
future commands.
To stop using the login configuration file for gcloud auth login commands, unset
the property with the following command:
gcloud config unset auth/login_config_file
gcloud auth login
To use the login configuration file directly with the gcloud auth login
command, complete the following instructions:
If you used the --activate flag when you created the login configuration
file, run the following command:
gcloud auth login
If you didn't use the --activate flag when you created the login
configuration file, run the following command:
Linux and macOS
gcloud auth login \
--login-config= LOGIN_CONFIG_PATH
Windows (PowerShell)
gcloud auth login `
--login-config= LOGIN_CONFIG_PATH
Replace LOGIN_CONFIG_PATH with the path of your login configuration file.
The gcloud auth login command stores access
credentials in your home directory. The authenticated principal becomes the active principal in
your active gcloud CLI configuration. Unless overridden, the gcloud CLI uses
these stored credentials to access Google Cloud.
Caution : Any user with access to your file system can use the stored access
credentials created by gcloud auth login. To reduce the consequences of a system
being compromised, strictly separate human and workload use, and don't use
gcloud auth login for automated workloads on remote systems with persistent
storage. Where possible, use a secret manager in combination with environment variables instead.
For more guidance on hardening remote systems, see
Best practices for protecting developer credentials .
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 WORKFORCE_PROVIDER_ID PATH_TO_OIDC_ID_TOKEN WORKFORCE_POOL_USER_PROJECT 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 "
}
}
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 WORKFORCE_POOL_ID SAML_ASSERTION_PATH 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 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:
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
Send feedback
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License , and code samples are licensed under the Apache 2.0 License . For details, see the Google Developers Site Policies . Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2026-09-30 UTC.
Need to tell us more?
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2026-09-30 UTC."],[],[]]
