Manage workforce identity pool providers

Preview — workforce identity federation

This feature is covered by the Pre-GA Offerings Terms of the Google Cloud Terms of Service. Pre-GA features might have limited support, and changes to pre-GA features might not be compatible with other pre-GA versions. For more information, see the launch stage descriptions.

This guide describes how to perform common operations with workforce identity federation.

Manage workforce pools and providers

You can set the allowed project as the billing/quota project for accessing workforce pool APIs.

Before you begin

1. Identify a billing/quota project.

   Note: Ask your Google Cloud account team to request access to workforce identity federation for this project. The account team notifies you when the project is granted access.

   To set the Google Cloud project that is billed and charged quota for operations performed in the gcloud CLI, execute the following command:

   gcloud config set billing/quota_project PROJECT_ID
   

   Replace PROJECT_ID with the project ID.

2. Alternatively, to learn how to set up workforce identity federation, see Configuring workforce identity federation. For IdP-specific instructions, see:

   • Configure workforce identity federation with Azure AD and sign in users
   • Configure workforce identity federation with Okta and sign in users

3. Install and initialize the Google Cloud CLI.

   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 federation pools.

Create a pool

To create a workforce pool, execute the following command:

gcloud iam workforce-pools create WORKFORCE_POOL_ID \
    --organization=ORGANIZATION_ID \
    --description=DESCRIPTION \
    --location=global

Replace the following:

• WORKFORCE_POOL_ID: a workforce pool ID that you choose
• ORGANIZATION_ID: your organization ID
• DESCRIPTION: the description of this pool

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 a provider, execute 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" \
    --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.

Note: For security reasons, OIDC_ISSUER_URL must be an HTTPS scheme URL.

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

• Configure workforce identity federation with Azure AD 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