Manage workforce identity pool providers

This guide describes how to perform common operations with workforce identity federation. To set up workforce identity federation, see Configuring workforce identity federation. For IdP-specific instructions, see the following guides: * Configure workforce identity federation with Azure AD and sign in users * Configure workforce identity federation with Okta and sign in users

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

Manage pools

This section shows you how to manage workforce identity pools.

Create a pool

To create a workforce pool, execute the following command:

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

gcloud iam workforce-pools create WORKFORCE_POOL_ID \
    --organization=ORGANIZATION_ID \
    --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.
  • DESCRIPTION: a workforce identity pool description.
  • SESSION_DURATION: 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 not configured, the session has a default duration of one hour (3600s).

Describe a pool

To describe a specific workforce pool, 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

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

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

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 pool providers:

Create a provider

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="OIDC_ISSUER_URL" \
    --client-id="OIDC_CLIENT_ID" \
    --web-sso-response-type="id-token" \
    --web-sso-assertion-claims-behavior="only-id-token-claims" \
    --attribute-mapping="ATTRIBUTE_MAPPING" \
    --attribute-condition="ATTRIBUTE_CONDITION"
    --location=global

Replace the following:

  • PROVIDER_ID the provider ID
  • WORKFORCE_POOL_ID: the workforce pool ID
  • DISPLAY_NAME: the display name
  • DESCRIPTION: the description
  • OIDC_ISSUER_URL: the OIDC issuer URL
  • OIDC_CLIENT_ID: the OIDC client ID
  • ATTRIBUTE_MAPPING: the attribute mapping; for example, google.subject=assertion.sub, google.groups=assertion.groupList, google.display_name=assertion.displayName,google.profile_photo=assertion.profilePhoto, attribute.costcenter=assertion.costcenter
  • ATTRIBUTE_CONDITION: the attribute condition; for example, assertion.group1=='gcp-users'.

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

This command assigns the subject, groupList, displayName, profilePhoto, and costcenter in the OIDC assertion to google.subject, google.groups, google.display_name, google.profile_photo, and attribute.costcenter attributes, respectively. The attribute condition ensures that only users in gcp-users group can sign in using this workforce provider. It configures the provider to only include ID token claims for attribute mapping and attribute condition.

Describe a provider

To describe a provider, execute 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

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

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

What's next