Manage workforce identity pool providers

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

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.

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.

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

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

Console

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:

      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.

   8. To create the provider, click Submit.

gcloud

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

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

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.

   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.

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

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.

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 more_vert 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