Stay organized with collections Save and categorize content based on your preferences.
This guide describes how you can perform common operations with Workforce Identity Federation. To set up Workforce Identity Federation, see the following guides:
You must have a Google Cloud organization set up.
After installing the Google Cloud CLI, initialize it 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 runninggcloud components update
.This section shows you how to manage workforce identity pools.
Create a poolTo create a workforce pool, execute the following command:
gcloudTo 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 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).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:
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).
Describe a pool gcloudTo describe a specific workforce pool using the gcloud CLI, execute the following command:
gcloud iam workforce-pools describe WORKFORCE_POOL_ID \
--location=global
Replace WORKFORCE_POOL_ID
with the workforce pool ID that you chose when you created the pool.
To describe a specific workforce pool using the Google Cloud console, do the following:
Go to the Workforce Identity Pools page:
In Workforce pools, select the pool
To list the workforce pools in the organization, execute the following command:
gcloud iam workforce-pools list \
--organization=ORGANIZATION_ID \
--location=global
Replace ORGANIZATION_ID with your organization ID.
ConsoleTo list workforce pools using the Google Cloud console, do the following:
Go to the Workforce Identity Pools page:
In the table, view the list of pools.
To update a specific workforce pool, execute the following command:
gcloud iam workforce-pools update WORKFORCE_POOL_ID \
--description=DESCRIPTION \
--location=global
Replace the following:
WORKFORCE_POOL_ID
: the workforce pool IDDESCRIPTION
: the description of the poolTo update a specific workforce pool using the Google Cloud console, do the following:
Go to the Workforce Identity Pools page:
In the table, select the pool.
Update the pool parameters.
Click Save Pool.
To delete a workforce identity pool, execute the following command:
gcloud iam workforce-pools delete WORKFORCE_POOL_ID \
--location=global
Replace WORKFORCE_POOL_ID
with the workforce pool ID.
To delete a specific workforce pool using the Google Cloud console, do the following:
Go to the Workforce Identity Pools page:
In Workforce pools, click more_vert Delete on the pool you want to delete.
Follow additional instructions.
You can undelete a workforce identity pool that was deleted within the last 30 days.
To undelete a pool, execute the following command:
gcloud iam workforce-pools undelete WORKFORCE_POOL_ID \
--location=global
Replace WORKFORCE_POOL_ID
with the workforce pool ID.
This section explains how you can use gcloud
commands to configure workforce identity pool providers:
This section describes how to create a workforce identity pool provider for an OIDC IdP.
gcloud Code flowTo create an OIDC provider that uses authorization code flow for web sign-in, 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" \
--client-secret-value="OIDC_CLIENT_SECRET" \ --web-sso-response-type="code" \ --web-sso-assertion-claims-behavior="merge-user-info-over-id-token-claims" \ --web-sso-additional-scopes="WEB_SSO_ADDITIONAL_SCOPES" \ --attribute-mapping="ATTRIBUTE_MAPPING" \ --attribute-condition="ATTRIBUTE_CONDITION" \ --jwk-json-path="JWK_JSON_PATH" \ --detailed-audit-logging \ --location=global
Replace the following:
WORKFORCE_PROVIDER_ID
: A unique workforce identity pool provider ID. The prefix gcp-
is reserved and can't be used in a workforce identity pool or workforce identity pool provider ID.WORKFORCE_POOL_ID
: The workforce identity pool ID to connect your IdP to.DISPLAY_NAME
: An optional user-friendly display name for the provider; for example, idp-eu-employees
.DESCRIPTION
: An optional workforce provider description; for example, IdP for Partner Example Organization employees
.ISSUER_URI
: The OIDC issuer URI, in a valid URI format, that starts with https
; for example, https://example.com/oidc
. Note: For security reasons, ISSUER_URI
must use the HTTPS scheme.OIDC_CLIENT_ID
: The OIDC client ID that is registered with your OIDC IdP; the ID must match the aud
claim of the JWT that is issued by your IdP.OIDC_CLIENT_SECRET
: The OIDC client secret.WEB_SSO_ADDITIONAL_SCOPES
: Optional additional scopes to send to the OIDC IdP for console (federated) or gcloud CLI browser-based sign-in.ATTRIBUTE_MAPPING
: An attribute mapping. The following is an example of an attribute mapping:
google.subject=assertion.sub,
google.groups=assertion.group1,
attribute.costcenter=assertion.costcenter
This example maps the IdP attributes subject
, group1
, and costcenter
in the OIDC assertion to google.subject
, google.groups
, and attribute.costcenter
attributes, respectively.ATTRIBUTE_CONDITION
: An attribute condition; for example, assertion.role == 'gcp-users'
. This example condition ensures that only users with the role gcp-users
can sign in using this provider. Warning: If your multi-tenant IdP has a single issuer URI, you must use attribute conditions to ensure that access is restricted to the correct tenant. For more information, see Use attribute conditions when federating with GitHub or other multi-tenant identity providers.JWK_JSON_PATH
: An optional path to a locally uploaded OIDC JWKs. If this parameter isn't supplied, Google Cloud instead uses your IdP's /.well-known/openid-configuration
path to source the JWKs containing the public keys. For more information about locally uploaded OIDC JWKs, see manage OIDC JWKs. Note: Local OIDC JWKs can be uploaded through implicit flow or code flow, but can only be used in programmatic flow, in which you directly call the STS /token
endpoint with a credential from the third-party IdP to exchange for a Google Cloud access token for your workforce pool.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.
locations/global/workforcePools/enterprise-example-organization-employees
. Implicit flow
To create an OIDC workforce identity pool provider that uses the implicit flow for web sign-in, run the following command:
gcloud iam workforce-pools providers create-oidc WORKFORCE_PROVIDER_ID \ --workforce-pool=WORKFORCE_POOL_ID \ --display-name="DISPLAY_NAME" \ --description="DESCRIPTION" \ --issuer-uri="ISSUER_URI" \ --client-id="OIDC_CLIENT_ID" \ --web-sso-response-type="id-token" \ --web-sso-assertion-claims-behavior="only-id-token-claims" \ --web-sso-additional-scopes="WEB_SSO_ADDITIONAL_SCOPES" \ --attribute-mapping="ATTRIBUTE_MAPPING" \ --attribute-condition="ATTRIBUTE_CONDITION" \ --jwk-json-path="JWK_JSON_PATH" \ --detailed-audit-logging \ --location=global
Replace the following:
WORKFORCE_PROVIDER_ID
: A unique workforce identity pool provider ID. The prefix gcp-
is reserved and can't be used in a workforce identity pool or workforce identity pool provider ID.WORKFORCE_POOL_ID
: The workforce identity pool ID to connect your IdP to.DISPLAY_NAME
: An optional user-friendly display name for the provider; for example, idp-eu-employees
.DESCRIPTION
: An optional workforce provider description; for example, IdP for Partner Example Organization employees
.ISSUER_URI
: The OIDC issuer URI, in a valid URI format, that starts with https
; for example, https://example.com/oidc
. Note: For security reasons, ISSUER_URI
must use the HTTPS scheme.OIDC_CLIENT_ID
: The OIDC client ID that is registered with your OIDC IdP; the ID must match the aud
claim of the JWT that is issued by your IdP.WEB_SSO_ADDITIONAL_SCOPES
: Optional additional scopes to send to the OIDC IdP for console (federated) or gcloud CLI browser-based sign-in.ATTRIBUTE_MAPPING
: An attribute mapping. The following is an example of an attribute mapping:
google.subject=assertion.sub,
google.groups=assertion.group1,
attribute.costcenter=assertion.costcenter
This example maps the IdP attributes subject
, group1
, and costcenter
in the OIDC assertion to google.subject
, google.groups
, and attribute.costcenter
attributes, respectively.ATTRIBUTE_CONDITION
: An attribute condition; for example, assertion.role == 'gcp-users'
. This example condition ensures that only users with the role gcp-users
can sign in using this provider. Warning: If your multi-tenant IdP has a single issuer URI, you must use attribute conditions to ensure that access is restricted to the correct tenant. For more information, see Use attribute conditions when federating with GitHub or other multi-tenant identity providers.JWK_JSON_PATH
: An optional path to a locally uploaded OIDC JWKs. If this parameter isn't supplied, Google Cloud instead uses your IdP's /.well-known/openid-configuration
path to source the JWKs containing the public keys. For more information about locally uploaded OIDC JWKs, see manage OIDC JWKs. Note: Local OIDC JWKs can be uploaded through implicit flow or code flow, but can only be used in programmatic flow, in which you directly call the STS /token
endpoint with a credential from the third-party IdP to exchange for a Google Cloud access token for your workforce pool.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.
locations/global/workforcePools/enterprise-example-organization-employees
. Console Code flow
In the Google Cloud console, go to the Workforce Identity Pools page:
In the Workforce Identity Pools table, select the pool for which you want to create the provider.
In the Providers table, click Add Provider.
In Select a protocol, select Open ID Connect (OIDC).
In Create a pool provider, do the following:
https
; for example, https://example.com/oidc
.aud
claim of the JWT that is issued by your IdP.In Flow type, do the following. Flow type is used only for a web-based single-sign-on flow.
In Assertion claims behavior, select either of the following:
Click Continue.
In Configure provider, you can configure an attribute mapping and an attribute condition. To create an attribute mapping, do the following. You can provide either the IdP field name or a CEL-formatted expression that returns a string.
Required: In OIDC 1, enter the subject from the IdP; for example, assertion.sub
.
Optional: To add additional attribute mappings, do the following:
To create an attribute condition, do the following:
Warning: If your multi-tenant IdP has a single issuer URI, you must use attribute conditions to ensure that access is restricted to the correct tenant. For more information, see Use attribute conditions when federating with GitHub or other multi-tenant identity providers.assertion.role == 'gcp-users'
. This example condition ensures that only users with the role gcp-users
can sign in using this provider.To turn on detailed audit logging, in Detailed logging, click the Enable detailed attribute value 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, 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.
To create the provider, click Submit.
In the Google Cloud console, go to the Workforce Identity Pools page:
In the Workforce Identity Pools table, select the pool for which you want to create the provider.
In the Providers table, click Add Provider.
In Select a protocol, select Open ID Connect (OIDC).
In Create a pool provider, do the following:
https
; for example, https://example.com/oidc
.aud
claim of the JWT that is issued by your IdP.In Flow type, do the following. Flow type is used only for a web-based single-sign-on flow.
In Configure provider, you can configure an attribute mapping and an attribute condition. To create an attribute mapping, do the following. You can provide either the IdP field name or a CEL-formatted expression that returns a string.
Required: In OIDC 1, enter the subject from the IdP; for example, assertion.sub
.
Optional: To add additional attribute mappings, do the following:
To create an attribute condition, do the following:
In Attribute Conditions, enter a condition in CEL format; for example, assertion.role == 'gcp-users'
. This example condition ensures that only users with the role gcp-users
can sign in using this provider.
To turn on detailed audit logging, in Detailed logging, click the Enable detailed attribute value 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, 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.
To create the provider, click Submit.
This section describes how to create a workforce identity pool provider for a SAML IdP.
gcloudTo create the provider, run the following command:
gcloud iam workforce-pools providers create-saml WORKFORCE_PROVIDER_ID \
--workforce-pool="WORKFORCE_POOL_ID" \
--attribute-mapping="ATTRIBUTE_MAPPING" \
--attribute-condition="ATTRIBUTE_CONDITION" \
--idp-metadata-path="XML_METADATA_PATH" \
--detailed-audit-logging \
--location="global"
Replace the following:
WORKFORCE_PROVIDER_ID
: the workforce provider IDWORKFORCE_POOL_ID
: the workforce pool IDATTRIBUTE_MAPPING
: an attribute mapping; for example, to map a subject, the attribute mapping is as follows:
google.subject=assertion.subject,
google.groups=assertion.attributes['https://example.com/aliases'],
attribute.department=assertion.attributes.department[0]
ATTRIBUTE_CONDITION
: an optional attribute condition; for example, assertion.subject.endsWith("@example.com")
XML_METADATA_PATH
: the path to the XML-formatted metadata file from your IdP
The prefix gcp-
is reserved and can't be used in a workforce identity pool or workforce identity pool provider ID.
This command assigns the subject and department in the SAML assertion to google.subject
and attribute.department
attributes, respectively. Additionally, the attribute condition ensures that only users with a subject ending in @example.com
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.
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:
In the Workforce Identity Pools table, select the pool for which you want to create the provider.
In the Providers table, click Add Provider.
In Select a protocol, select SAML.
In Create a pool provider 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.
Ensure that Enabled provider is enabled.
Click Continue.
In Configure provider, do the following:
In Attribute mapping, enter a CEL expression for google.subject
.
Optional: To enter other mappings, click Add mapping and enter other mappings—for example:
google.subject=assertion.subject,
google.groups=assertion.attributes['https://example.com/aliases'],
attribute.costcenter=assertion.attributes.costcenter[0]
This example maps the IdP attributes assertion.subject
, assertion.attributes['https://example.com/aliases']
, and assertion.attributes.costcenter[0]
to the Google Cloud attributes google.subject
, google.groups
, and google.costcenter
, respectively.Optional: To add an attribute condition, click Add condition and enter a CEL expression representing an attribute condition. For example, to limit the ipaddr
attribute to a certain IP range you can set the condition assertion.attributes.ipaddr.startsWith('98.11.12.')
. This example condition ensures that only users with an IP address that starts with 98.11.12.
can sign in using this workforce provider.
Click Continue.
To turn on detailed audit logging, in Detailed logging, click the Enable detailed attribute value 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, 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.
To create the provider, click Submit.
To describe a provider, run the following command:
gcloud iam workforce-pools providers describe PROVIDER_ID \
--workforce-pool=WORKFORCE_POOL_ID \
--location=global
Replace the following:
PROVIDER_ID
: the provider IDWORKFORCE_POOL_ID
: the workforce pool IDTo view a provider, do the following:
Go to Workforce Identity Pools
In the table, select the pool for which you want to view the provider.
In the Providers table, select the provider.
To list providers, execute the following command:
gcloud iam workforce-pools providers list \
--workforce-pool=WORKFORCE_POOL_ID \
--location=global
Replace WORKFORCE_POOL_ID
with the workforce pool ID.
To view a provider, do the following:
Go to Workforce Identity Pools
In the table, select the pool for which you want to list the providers.
In the Providers table you can see a list of providers.
To update an OIDC provider after creation, execute the following command:
gcloud iam workforce-pools providers update-oidc PROVIDER_ID \
--workforce-pool=WORKFORCE_POOL_ID \
--description="DESCRIPTION" \
--detailed-audit-logging \
--location=global
Replace the following:
PROVIDER_ID
: the provider IDWORKFORCE_POOL_ID
: the workforce pool IDDESCRIPTION
: the description--detailed-audit-logging
flag to gcloud iam workforce-pools providers update
. To disable detailed audit logging, add the --no-detailed-audit-logging
flag to the update command.To view a provider, do the following:
Go to Workforce Identity Pools
In the table, select the pool for which you want to view the provider.
In the Providers table, click more_vert Edit.
Update the provider.
To save the updated provider, click Save.
To delete a provider, execute the following command:
gcloud iam workforce-pools providers delete PROVIDER_ID \
--workforce-pool=WORKFORCE_POOL_ID \
--location=global
Replace the following:
PROVIDER_ID
: the provider IDWORKFORCE_POOL_ID
: the workforce pool IDTo undelete a provider deleted within the last 30 days, execute the following command:
gcloud iam workforce-pools providers undelete PROVIDER_ID \
--workforce-pool=WORKFORCE_POOL_ID \
--location=global
Replace the following:
PROVIDER_ID
: the provider IDWORKFORCE_POOL_ID
: the workforce pool IDThis section shows you how to manage OIDC JWKs in workforce pool providers.
Create a provider and upload OIDC JWKsTo create OIDC JWKs, see JWT, JWS, JWE, JWK, and JWA Implementations.
To upload an OIDC JWK file when you create a workforce pool provider, run the gcloud iam workforce-pools providers create-oidc command with --jwk-json-path="JWK_JSON_PATH"
. Replace JWK_JSON_PATH
with the path to the JWKs JSON file.
This operation uploads the keys from the file.
Update OIDC JWKsTo update OIDC JWKs, run the gcloud iam workforce-pools providers update-oidc command with --jwk-json-path="JWK_JSON_PATH"
. Replace JWK_JSON_PATH
with the path to the JWKs JSON file.
This operation replaces any existing uploaded keys with the ones in the file.
Delete all uploaded OIDC JWKsTo delete all of the uploaded OIDC JWKs and instead use the issuer URI to fetch the keys, run the gcloud iam workforce-pools providers update-oidc command with --jwk-json-path="JWK_JSON_PATH"
. Replace JWK_JSON_PATH
with the path to an empty file. Use the --issuer-uri
flag to set the issuer URI.
This operation deletes all of your existing uploaded keys.
What's nextExcept 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 2025-07-16 UTC.
[[["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 2025-07-16 UTC."],[[["This guide covers the management of Workforce Identity Pools and their providers, including creating, describing, listing, updating, deleting, and undeleting them through both the Google Cloud console and the `gcloud` command-line tool."],["It details how to create OIDC (OpenID Connect) providers for workforce identity pools, supporting both authorization code flow and implicit flow, and explains the necessary steps and parameters for each using both the console and the gcloud CLI."],["The guide explains the process of creating SAML (Security Assertion Markup Language) providers, emphasizing the use of an IDP metadata file and configuring attribute mappings and conditions for access control."],["The guide provides instructions on how to manage OIDC JWKs (JSON Web Keys) within workforce pool providers, including uploading, updating, and deleting them to control the source of public keys."],["Before utilizing Workforce Identity Federation, it is necessary to have a Google Cloud Organization established and correctly initialized gcloud CLI."]]],[]]
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4