Manage workforce identity pool providers

This guide describes how you can perform common operations with Workforce Identity Federation. To set up Workforce Identity Federation, see the following guides:

• Configure Workforce Identity Federation with Microsoft Entra ID and sign in users
• Configure Workforce Identity Federation with Okta and sign in users
• Configure Workforce Identity Federation on an IdP that supports OIDC or SAML

Before you begin

1. You must have a Google Cloud organization set up.

2. Install the Google Cloud CLI, then initialize it by running the following command:

   gcloud init

   Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.

Manage pools

This section shows you how to manage workforce identity pools.

Create a pool

To create a workforce pool, execute the following command:

Console

To create the workforce identity pool, do the following:

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

   Go to Workforce Identity Pools

2. Click Create pool and do the following:

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

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

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

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

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

gcloud

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

gcloud iam workforce-pools create WORKFORCE_POOL_ID \
    --organization=ORGANIZATION_ID \
    --display-name="DISPLAY_NAME" \
    --description="DESCRIPTION" \
    --session-duration=SESSION_DURATION \
    --location=global

Replace the following:

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

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

Describe a pool

Console

To describe a specific workforce pool using the Google Cloud console, do the following:

1. Go to the Workforce Identity Pools page:

   Go to Workforce Identity Pools

2. In Workforce pools, select the pool

gcloud

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

List pools

Console

To list workforce pools using the Google Cloud console, do the following:

1. Go to the Workforce Identity Pools page:

   Go to Workforce Identity Pools

2. In the table, view the list of pools.

gcloud

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.

Update a pool

Console

To update a specific workforce pool using the Google Cloud console, do the following:

1. Go to the Workforce Identity Pools page:

   Go to Workforce Identity Pools

2. In the table, select the pool.

3. Update the pool parameters.

4. Click Save Pool.

gcloud

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 ID
• DESCRIPTION: the description of the pool

Delete a pool

Console

To delete a specific workforce pool using the Google Cloud console, do the following:

1. Go to the Workforce Identity Pools page:

   Go to Workforce Identity Pools

2. In Workforce pools, click Delete on the pool you want to delete.

3. Follow additional instructions.

gcloud

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.

Undelete a pool

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.

Configure a provider within the workforce pool

This section explains how you can use gcloud commands to configure workforce identity pool providers:

Create an OIDC provider

This section describes how to create a workforce identity pool provider for an OIDC IdP.

Console

Code flow

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

   Go to Workforce Identity Pools

2. In the Workforce Identity Pools table, select the pool for which you want to create the provider.

3. In the Providers table, click Add Provider.

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

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

   1. In Name, enter a name for the provider.
   2. In Issuer (URL), enter the issuer URI. The OIDC issuer URI must be in a valid URI format and start with https; for example, https://example.com/oidc.
   3. Enter the Client ID, the OIDC client ID that is registered with your OIDC IdP; the ID must match the aud claim of the JWT that is issued by your IdP.
   4. To create a provider that is enabled, make sure Enabled Provider is on.
   5. Click Continue.

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

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

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

      • User info and ID token
      • Only ID token

   4. Click Continue.

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

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

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

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

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

      Warning: If your multi-tenant IdP has a single issuer URI, you must use attribute conditions to ensure that access is restricted to the correct tenant. For more information, see Use attribute conditions when federating with GitHub or other multi-tenant identity providers.
      1. Click Add condition.
      2. In Attribute Conditions, enter a condition in CEL format; for example, assertion.role == 'gcp-users'. This example condition ensures that only users with the role gcp-users can sign in using this provider.

8. To create the provider, click Submit.

   Implicit flow

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

      Go to Workforce Identity Pools

   2. In the Workforce Identity Pools table, select the pool for which you want to create the provider.

   3. In the Providers table, click Add Provider.

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

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

      1. In Name, enter a name for the provider.
      2. In Issuer (URL), enter the issuer URI. The OIDC issuer URI must be in a valid URI format and start with https; for example, https://example.com/oidc.
      3. Enter the Client ID, the OIDC client ID that is registered with your OIDC IdP; the ID must match the aud claim of the JWT that is issued by your IdP.
      4. To create a provider that is enabled, make sure Enabled Provider is on.
      5. Click Continue.

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

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

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

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

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

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

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

         1. Click Add condition.

         2. In Attribute Conditions, enter a condition in CEL format; for example, 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.

   8. To create the provider, click Submit.

gcloud

Code flow

To create an OIDC provider that uses authorization code flow for web sign-in, run the following command:

gcloud iam workforce-pools providers create-oidc PROVIDER_ID \
    --workforce-pool=WORKFORCE_POOL_ID \
    --display-name="DISPLAY_NAME" \
    --description="DESCRIPTION" \
    --issuer-uri="ISSUER_URI" \
    --client-id="OIDC_CLIENT_ID" \
    --client-secret-value="OIDC_CLIENT_SECRET" \
    --web-sso-response-type="code" \
    --web-sso-assertion-claims-behavior="merge-user-info-over-id-token-claims" \
    --web-sso-additional-scopes="WEB_SSO_ADDITIONAL_SCOPES" \
    --attribute-mapping="ATTRIBUTE_MAPPING" \
    --attribute-condition="ATTRIBUTE_CONDITION" \
    --jwk-json-path="JWK_JSON_PATH" \
    --location=global

Replace the following:

• PROVIDER_ID: A unique provider ID. The prefix gcp- is reserved and can't be used in a pool or provider ID.
• WORKFORCE_POOL_ID: The workforce 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.

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 workforce identity pool provider that uses the implicit flow for web sign-in, run the following command:

gcloud iam workforce-pools providers create-oidc PROVIDER_ID \
    --workforce-pool=WORKFORCE_POOL_ID \
    --display-name="DISPLAY_NAME" \
    --description="DESCRIPTION" \
    --issuer-uri="ISSUER_URI" \
    --client-id="OIDC_CLIENT_ID" \
    --web-sso-response-type="id-token" \
    --web-sso-assertion-claims-behavior="only-id-token-claims" \
    --web-sso-additional-scopes="WEB_SSO_ADDITIONAL_SCOPES" \
    --attribute-mapping="ATTRIBUTE_MAPPING" \
    --attribute-condition="ATTRIBUTE_CONDITION" \
    --jwk-json-path="JWK_JSON_PATH" \
    --location=global

Replace the following:

• PROVIDER_ID: A unique provider ID. The prefix gcp- is reserved and can't be used in a pool or provider ID.
• WORKFORCE_POOL_ID: The workforce 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.

In the command response, POOL_RESOURCE_NAME is the name of the pool; for example, locations/global/workforcePools/enterprise-example-organization-employees.

Create a SAML provider

This section describes how to create a workforce identity pool provider for a SAML IdP.

Console

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

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

   Go to Workforce Identity Pools

2. In the Workforce Identity Pools table, select the pool for which you want to create the provider.

3. In the Providers table, click Add Provider.

4. In Select a protocol, select SAML.

5. In Create a pool provider do the following:

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

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

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

   4. Ensure that Enabled provider is enabled.

   5. Click Continue.

6. In Configure provider, do the following:

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

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

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

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

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

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

   4. Click Continue.

7. To create the provider, click Submit.

gcloud

To 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" \
    --location="global"

Replace the following:

• WORKFORCE_PROVIDER_ID: the workforce provider ID
• WORKFORCE_POOL_ID: the workforce pool ID

• ATTRIBUTE_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 pool or 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.

Describe a provider

Console

To view a provider, do the following:

1. Go to the Workforce Identity Pools page:

Go to Workforce Identity Pools

1. In the table, select the pool for which you want to view the provider.

2. In the Providers table, select the provider.

gcloud

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 ID
• WORKFORCE_POOL_ID: the workforce pool ID

List providers

Console

To view a provider, do the following:

1. Go to the Workforce Identity Pools page:

Go to Workforce Identity Pools

1. In the table, select the pool for which you want to list the providers.

2. In the Providers table you can see a list of providers.

gcloud

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.

Update a provider

Console

To view a provider, do the following:

1. Go to the Workforce Identity Pools page:

Go to Workforce Identity Pools

1. In the table, select the pool for which you want to view the provider.

2. In the Providers table, click Edit.

3. Update the provider.

4. To save the updated provider, click Save.

gcloud

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" \
    --location=global

Replace the following:

• PROVIDER_ID: the provider ID
• WORKFORCE_POOL_ID: the workforce pool ID
• DESCRIPTION: the description

Delete a provider

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 ID
• WORKFORCE_POOL_ID: the workforce pool ID

Undelete a provider

To 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 ID
• WORKFORCE_POOL_ID: the workforce pool ID

Manage OIDC JWKs

This section shows you how to manage OIDC JWKs in workforce pool providers.

Create a provider and upload OIDC JWKs

To 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 JWKs

To 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 JWKs

To 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 next

• Configure Workforce Identity Federation with Microsoft Entra ID and sign in users
• Configure Workforce Identity Federation with Okta and sign in users
• Delete Workforce Identity Federation users and their data
• Learn which Google Cloud products support Workforce Identity Federation