Manage workload identity pools and providers

This page explains how to manage your existing workload identity pools and their identity providers.

You can manage pools and providers using the Google Cloud console, the Google Cloud CLI, or the REST API.

Before you begin

Create a workload identity pool. See one of the following pages to learn how:

• Access resources from AWS
• Access resources from Microsoft Azure
• Access resources from an OIDC identity provider
• Access resources from a SAML 2.0 identity provider

Required roles

To get the permissions that you need to manage workload identity pools and providers, ask your administrator to grant you the following IAM roles on the project:

• To view pools and providers: IAM Workload Identity Pool Viewer (roles/iam.workloadIdentityPoolViewer)
• To view, create, update, and delete pools and providers: IAM Workload Identity Pool Admin (roles/iam.workloadIdentityPoolAdmin)

For more information about granting roles, see Manage access.

These predefined roles contain the permissions required to manage workload identity pools and providers. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

• To view workload identity pools and providers:
  • iam.googleapis.com/workloadIdentityPoolProviders.get
  • iam.googleapis.com/workloadIdentityPoolProviders.list
  • iam.googleapis.com/workloadIdentityPools.get
  • iam.googleapis.com/workloadIdentityPools.list
• To create, update, and delete pools and providers:
  • iam.googleapis.com/workloadIdentityPoolProviders.create
  • iam.googleapis.com/workloadIdentityPoolProviders.delete
  • iam.googleapis.com/workloadIdentityPoolProviders.undelete
  • iam.googleapis.com/workloadIdentityPoolProviders.update
  • iam.googleapis.com/workloadIdentityPools.create
  • iam.googleapis.com/workloadIdentityPools.delete
  • iam.googleapis.com/workloadIdentityPools.undelete
  • iam.googleapis.com/workloadIdentityPools.update

You might also be able to get these permissions with custom roles or other predefined roles.

Manage workload identity pools

List pools

To list all the workload identity pools in a project, do the following:

Console

In the Google Cloud console, go to the Workload Identity Pools page.

Go to Workload Identity Pools

gcloud CLI

Execute the gcloud iam workload-identity-pools list command.

REST

Call projects.locations.workloadIdentityPools.list().

Get a pool

To get details for a specific workload identity pool, do the following:

Console

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

   Go to Workload Identity Pools

2. Find the workload identity pool that you want to view, then click its Edit icon. The Google Cloud console shows details about the workload identity pool.

gcloud CLI

Execute the gcloud iam workload-identity-pools describe command.

REST

Call projects.locations.workloadIdentityPools.get().

Update a pool

You can enable or disable a workload identity pool. You can also change its display name or description.

To update an existing workload identity pool, do the following:

Console

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

   Go to Workload Identity Pools

2. Find the workload identity pool that you want to edit, then click its Edit icon.

   To disable or enable the workload identity pool, click the Status toggle, then click Disable or Enable.

   To edit the display name, click Edit next to the display name. Update the name, then click Save.

   To edit the description, use the gcloud CLI or the REST API.

gcloud CLI

Execute the gcloud iam workload-identity-pools update command.

REST

Call projects.locations.workloadIdentityPools.patch().

Delete a pool

When you delete a workload identity pool, you also delete its workload identity pool providers. As a result, the identities in the pool lose access to Google Cloud resources.

Caution: Before you delete a workload identity pool, consider disabling the pool or disabling its identity providers. If one of your workloads loses access to Google Cloud resources as a result, you can re-enable the pool and its providers at any time. If your workloads do not lose access, then it is safe to delete the pool.

You can undelete a pool for up to 30 days after deletion. After 30 days, deletion is permanent. Until a pool is permanently deleted, you cannot reuse its name when creating a new workload identity pool.

To delete a workload identity pool and its identity providers, do the following:

Console

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

   Go to Workload Identity Pools

2. Find the workload identity pool that you want to delete, then click its Edit icon.

3. Click Delete pool, then click Delete. The workload identity pool and its identity providers are deleted.

gcloud CLI

Execute the gcloud iam workload-identity-pools delete command.

REST

Call projects.locations.workloadIdentityPools.delete().

Undelete a pool

You can recover a deleted workload identity pool for up to 30 days after deletion.

To undelete a pool, do the following:

Console

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

   Go to Workload Identity Pools

2. Click the Show deleted pools and providers toggle.

3. Find the workload identity pool that you want to undelete, then click its Restore icon.

4. Click Restore. The pool and its providers are restored.

gcloud CLI

Execute the gcloud iam workload-identity-pools undelete command.

REST

Call projects.locations.workloadIdentityPools.undelete().

Manage workload identity pool providers

Create a provider

To create a workload identity pool provider in an existing workload identity pool, do the following:

Console

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

   Go to Workload Identity Pools

2. Find the workload identity pool that you want to add a provider to, then click its Edit icon.

3. Click Add provider.

4. Select the type of provider to create:

   • AWS: An Amazon Web Services (AWS) identity provider.
   • OpenID Connect (OIDC): An OIDC-compatible identity provider. This includes Microsoft Azure.

5. Enter a name for the provider.

   The Google Cloud console uses the name to create a provider ID. To change the provider ID, click Edit. You cannot change the provider ID later.

6. Complete the remaining fields for your provider:

   • AWS: Enter your AWS account ID.
   • OIDC: Enter the issuer URL. For Azure, the issuer URL uses the format https://sts.windows.net/AZURE_TENANT_ID. For other providers, consult the provider's documentation.

   When you are done, click Continue.

7. To configure the attribute mapping, click Edit mapping. Attribute mapping lets you use information about external identities to grant access to a subset of those identities.

   • AWS: This step is optional; you can use the default mapping.

     For details, see Identity provider settings for AWS.

   • OIDC: We recommend mapping google.subject to assertion.sub. Other mappings are optional.

     For details, see Identity provider settings for Azure or Identity provider settings for OIDC.

8. Optional: To provide an attribute condition, which specifies the identities that can authenticate, click Add condition and enter a valid Common Expression Language (CEL) expression. For details, see Attribute conditions.

9. Click Save. The workload identity pool provider is created.

gcloud CLI

Execute the gcloud iam workload-identity-pools providers create-aws command to create an AWS provider.

Execute the gcloud iam workload-identity-pools providers create-oidc command to create an OIDC provider. This includes Microsoft Azure.

REST

Call projects.locations.workloadIdentityPools.providers.create().

List providers

To list the workload identity pool providers in a project, do the following:

Console

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

   Go to Workload Identity Pools

2. To view the providers for a workload identity pool, click the Expand node icon for the pool.

gcloud CLI

Execute the gcloud iam workload-identity-pools providers list command.

REST

Call projects.locations.workloadIdentityPools.providers.list().

Get a provider

To get details for a specific workload identity pool provider, do the following:

Console

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

   Go to Workload Identity Pools

2. Find the workload identity pool that contains the provider, then click the Expand node icon for the pool.

3. Find the workload identity pool provider that you want to view, then click its Edit icon. The Google Cloud console shows detailed information about the provider.

gcloud CLI

Execute the gcloud iam workload-identity-pools providers describe command.

REST

Call projects.locations.workloadIdentityPools.providers.get().

Update a provider

You can enable or disable a workload identity pool provider. You can also update its account information and its attribute mapping, as well as its display name and description.

To update an existing workload identity pool provider, do the following:

Console

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

   Go to Workload Identity Pools

2. Find the workload identity pool that contains the provider, then click the Expand node icon for the pool.

3. Find the workload identity pool provider that you want to edit, then click its Edit icon.

4. Edit the provider's information, then click Save.

gcloud CLI

Execute the gcloud iam workload-identity-pools providers update-aws command to update an AWS provider.

Execute the gcloud iam workload-identity-pools providers update-oidc command to update an OIDC provider. This includes Microsoft Azure.

REST

Call projects.locations.workloadIdentityPools.providers.patch().

Delete a provider

When you delete a workload identity pool provider, the provider's identities lose access to Google Cloud resources.

Caution: Before you delete a workload identity pool provider, consider disabling the provider. If one of your workloads loses access to Google Cloud resources as a result, you can re-enable the provider at any time. If your workloads do not lose access, then it is safe to delete the provider.

You can undelete a provider for up to 30 days after deletion. After 30 days, deletion is permanent. Until a provider is permanently deleted, you cannot reuse its name when creating a new provider.

To delete a workload identity pool provider, do the following:

Console

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

   Go to Workload Identity Pools

2. Find the workload identity pool that contains the provider, then click its Edit icon.

3. In the Providers pane, find the provider that you want to delete, then click its Delete icon.

4. Click Delete to delete the provider.

gcloud CLI

Execute the gcloud iam workload-identity-pools providers delete command.

REST

Call projects.locations.workloadIdentityPools.providers.delete().

Undelete a provider

You can recover a deleted workload identity pool provider for up to 30 days after deletion. To undelete a provider:

Console

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

   Go to Workload Identity Pools

2. Click the Show deleted pools and providers toggle.

3. Find the workload identity pool that contains the provider, then click the Expand node icon for the pool.

4. Find the provider that you want to undelete, then click its Restore icon.

5. Click Restore. The provider is restored.

gcloud CLI

Execute the gcloud iam workload-identity-pools providers undelete command.

REST

Call projects.locations.workloadIdentityPools.providers.undelete().

Manage constraints for workload identity federation

You can use organization policy constraints to restrict how resources in your Google Cloud organization can be used.

This section describes constraints that are recommended when you use workload identity federation.

Restrict identity provider configuration

As an organization administrator, you can decide which identity providers your organization is allowed to federate with.

To manage which identity providers are allowed, enable the constraints/iam.workloadIdentityPoolProviders list constraint in the organization policy for your organization. This constraint specifies the issuer URIs of the allowed providers. You can use the Google Cloud console or the Google Cloud CLI to enable this constraint.

Note: This constraint only limits creating and updating identity providers. If an identity provider was configured before you enabled the constraint, that provider can still be used.

To only allow federation from AWS, create a single constraint with the URI https://sts.amazonaws.com. The following example shows how to create this constraint using the gcloud CLI:

gcloud resource-manager org-policies allow constraints/iam.workloadIdentityPoolProviders \
     https://sts.amazonaws.com --organization=ORGANIZATION_NUMBER

You can also specify which AWS account IDs have access to your Google Cloud resources. To specify the account IDs, use the constraints/iam.workloadIdentityPoolAwsAccounts list constraint:

gcloud resource-manager org-policies allow constraints/iam.workloadIdentityPoolAwsAccounts \
    ACCOUNT_ID --organization=ORGANIZATION_NUMBER

To only allow federation from one OIDC provider, create a single constraint with the issuer_uri of the allowed provider. For example, the following only allows federation from a specific Azure tenant:

gcloud resource-manager org-policies allow constraints/iam.workloadIdentityPoolProviders \
     https://sts.windows.net/AZURE_TENANT_ID --organization=ORGANIZATION_NUMBER

Federation from a SAML identity provider is a special case because the public keys used to validate the assertion are provided at configuration time instead of fetched directly from the identity provider. It is therefore conceivable that a malicious user could try to upload a SAML metadata document with your organization's identity provider's entity ID but a public key for which they have access to the private key. Restricting federation by the entity ID in this scenario gives only an illusion of security. For this reason we strongly advise that you only allow the creation of a workload identity pool allowing SAML federation in a GCP project that your organization centrally manages. You can then grant external identities in that workload identity pool access to resources across your organization.

To allow federation from from SAML identity providers, create a constraint allowing the special keyword KEY_UPLOAD.

gcloud resource-manager org-policies allow constraints/iam.workloadIdentityPoolProviders \
     KEY_UPLOAD --organization=ORGANIZATION_NUMBER

You can repeat these commands to allow federation from additional providers.

To block federation from all providers:

1. Create a YAML file containing the following:

   constraint: constraints/iam.workloadIdentityPoolProviders
   listPolicy:
     allValues: DENY
   

2. Pass the file to the gcloud resource-manager org-policies set-policy command:

   gcloud resource-manager org-policies set-policy FILE_NAME.yaml \
       --organization=ORGANIZATION_NUMBER
   

Restrict service account key creation

Workload identity federation lets you access Google Cloud resources from outside of Google Cloud without using a service account key. If you never use service account keys to authenticate, you can help reduce risk by disabling key creation.

To disable the creation of service account keys, enforce the iam.disableServiceAccountKeyCreation boolean constraint in the organization policy for your organization. You can also enforce the iam.disableServiceAccountKeyUpload boolean constraint, which disables uploading of public keys for service accounts.

You can use the Google Cloud console or the gcloud CLI to enable these constraints. For example, the following gcloud CLI commands enable both constraints:

gcloud resource-manager org-policies enable-enforce \
    constraints/iam.disableServiceAccountKeyCreation \
    --organization=ORGANIZATION_NUMBER
gcloud resource-manager org-policies enable-enforce \
    constraints/iam.disableServiceAccountKeyUpload \
    --organization=ORGANIZATION_NUMBER

Monitor workload identity federations

Workload identity federation provides multiple Cloud Monitoring metrics for you to monitor your workload identity pools and providers. See the Cloud Monitoring documentation for more information about viewing or setting up custom alerting on these metrics.

Metric type ^Launch stage Display name
Kind, Type, Unit Monitored resources	Description Labels
iam.googleapis.com/workload_identity_federation/count ^BETA Workload identity federation count
DELTA, INT64, 1 iam.googleapis.com/WorkloadIdentityPoolProvider	Count of token exchanges using workload identity federation. result: If the request succeeds, the value is success. If the request fails, the value matches one of the possible OAuth 2.0 error types documented at https://tools.ietf.org/html/rfc6749#section-5.2, for example, invalid_client.
iam.googleapis.com/workload_identity_federation/key_usage_count Workload identity federation key usage count. This metric currently only tracks SAML keys.
DELTA, INT64, 1 iam.googleapis.com/WorkloadIdentityPoolProvider	Count of times a key is used as part of workload identity federation. key: The identifier of a public key used during a workload identity federation. use: What the key was used for. The following are possible values for use (additional values might be added in the future): verify: verify a signature

What's next

Learn more about workload identity federation.