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
You must have a Google Cloud organization set up.
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 IDDESCRIPTION
: 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 IDWORKFORCE_POOL_ID
: the workforce pool IDDISPLAY_NAME
: the display nameDESCRIPTION
: the descriptionOIDC_ISSUER_URL
: the OIDC issuer URLOIDC_CLIENT_ID
: the OIDC client IDATTRIBUTE_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 IDWORKFORCE_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 IDWORKFORCE_POOL_ID
: the workforce pool IDDESCRIPTION
: 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 IDWORKFORCE_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 IDWORKFORCE_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