This page describes how to configure your workloads to access Google Cloud resources by using Workload Identity Federation and either direct resource access or service account impersonation .
You can find end-to-end, use case-specific instructions in configuration guides for AWS and Azure , Active Directory , GitHub, GitLab, and other deployment pipelines , and Kubernetes .
Allow your external workload to access Google Cloud resources
To provide your workload with access to Google Cloud resources, we recommend that you grant direct resource access to the principal. In this case, the principal is the federated user. Some Google Cloud products have Google Cloud API limitations . If your workload calls an API endpoint that has a limitation, you can instead use service account impersonation. In this case, the principal is the Google Cloud service account, which acts as the identity. You grant access to the service account on the resource.
Direct resource access
You can grant access to a federated identity directly on resources by using the Google Cloud console or the gcloud CLI.
Console
To use the Google Cloud console to grant IAM roles
directly on a resource, you must go to the resource's page, and then
grant the role. The following example shows you how to go
to the Cloud Storage page and grant the role Storage Object Viewer
( roles/storage.objectViewer
) to a federated identity directly on a
Cloud Storage bucket.
- In the Google Cloud console, go to the Cloud Storage Buckets
page.
-
In the list of buckets, click the name of the bucket for which you want to grant the role.
-
Select the Permissionstab near the top of the page.
-
Click the add_box Grant accessbutton.
The Add principalsdialog appears.
-
In the New principalsfield, enter one or more identities that need access to your bucket.
By subject
principal://iam.googleapis.com/projects/ PROJECT_NUMBER /locations/global/workloadIdentityPools/ POOL_ID /subject/ SUBJECT
Replace the following:
-
PROJECT_NUMBER
: the project number -
POOL_ID
: the workload pool ID -
SUBJECT
: the individual subject mapped from your IdP—for example,administrator@example.com
By group
principalSet://iam.googleapis.com/projects/ PROJECT_NUMBER /locations/global/workloadIdentityPools/ POOL_ID /group/ GROUP
Replace the following:
-
PROJECT_NUMBER
: the project number -
WORKLOAD_POOL_ID
: the workload pool ID -
GROUP
: the group mapped from your IdP—for example:administrator-group@example.com
By attribute
principalSet://iam.googleapis.com/projects/ PROJECT_NUMBER /locations/global/workloadIdentityPools/ POOL_ID /attribute. ATTRIBUTE_NAME / ATTRIBUTE_VALUE
Replace the following:
-
PROJECT_NUMBER
: the project number -
WORKLOAD_POOL_ID
: the workload pool ID -
ATTRIBUTE_NAME
: one of the attributes that was mapped from your IdP -
ATTRIBUTE_VALUE
: the value of the attribute
-
-
Select a role (or roles) from the Select a roledrop-down menu. The roles you select appear in the pane with a short description of the permissions they grant.
-
Click Save.
gcloud
To use the gcloud CLI to grant IAM roles on a resource in a project, do the following:
-
Obtain the project number of the project in which the resource is defined.
gcloud projects describe $(gcloud config get-value core/project) --format=value\(projectNumber\)
-
Grant access to the resource.
To use the gcloud CLI to grant the role Storage Object Viewer (
roles/storage.objectViewer
) to external identities that meet certain criteria, run the following command.By subject
gcloud storage buckets add-iam-policy-binding BUCKET_ID \ --role=roles/storage.objectViewer \ --member="principal://iam.googleapis.com/projects/ PROJECT_NUMBER /locations/global/workloadIdentityPools/ POOL_ID /subject/ SUBJECT "
By group
gcloud storage buckets add-iam-policy-binding BUCKET_ID \ --role=roles/storage.objectViewer \ --member="principalSet://iam.googleapis.com/projects/ PROJECT_NUMBER /locations/global/workloadIdentityPools/ POOL_ID /group/ GROUP "
By attribute
gcloud storage buckets add-iam-policy-binding BUCKET_ID \ --role=roles/storage.objectViewer \ --member="principalSet://iam.googleapis.com/projects/ PROJECT_NUMBER /locations/global/workloadIdentityPools/ POOL_ID /attribute. ATTRIBUTE_NAME / ATTRIBUTE_VALUE "
Replace the following:
-
BUCKET_ID
: the bucket on which to grant access -
PROJECT_NUMBER
: the project number . of the project that contains the workload identity pool -
POOL_ID
: the pool ID of the workload identity pool -
SUBJECT
: the expected value for the attribute that you've mapped togoogle.subject
-
GROUP
: the expected value for the attribute that you've mapped togoogle.groups
-
ATTRIBUTE_NAME
: the name of a custom attribute in your attribute mapping -
ATTRIBUTE_VALUE
: the value of the custom attribute in your attribute mapping
You can grant roles on any Google Cloud resource that supports IAM allow policies.
-
Service account impersonation
-
To create a service account for the external workload, do the following:
-
Enable the IAM, Security Token Service, and Service Account Credentials APIs.
-
Create a service account that represents the workload. We recommend that you use a dedicated service account for each workload . The service account doesn't need to be in the same project as the workload identity pool, but you must refer to the project that contains the service account.
-
Grant the service account access to resources that you want external identities to access.
-
Grant the Workload Identity User role (
roles/iam.workloadIdentityUser
) to the service account.
-
-
To grant access to a federated identity using service account impersonation using the Google Cloud console or the gcloud CLI:
Console
To use the Google Cloud console to grant IAM roles to a federated identity with service account, do the following:
Service Account in the same project
-
To grant access using service account impersonation for a service account in the same project, do the following:
-
Go to the Workload Identity Poolspage.
-
Select Grant access.
-
In the Grant access to service accountdialog, select Grant access using Service Account impersonation.
-
In the Service accountslist, select the service account for the external identities to impersonate, and do the following:
-
To choose which identities in the pool can impersonate the service account, perform one of the following actions:
-
To allow only specific identities of the workload identity pool to impersonate the service account, select Only identities matching the filter.
-
In the Attribute namelist, select the attribute that you want to filter on.
-
In the Attribute valuefield, enter the expected value of the attribute; for example, if you use an attribute mapping
google.subject=assertion.sub
, set Attributename tosubject
and Attribute valueto the value of thesub
claim in tokens that are issued by your external identity provider.
-
-
To save the configuration, click Saveand then Dismiss.
-
Service account in a different project
-
To grant access using service account impersonation for a service account in a different project, do the following:
-
Go to the Service Accountspage.
-
Select the service account that you want to impersonate.
-
Click Manage access.
-
Click Add principal.
-
In the New principalfield, enter one of the following principal identifiers for the identities in your pool that will impersonate the service account.
By subject
principal://iam.googleapis.com/projects/ PROJECT_NUMBER /locations/global/workloadIdentityPools/ POOL_ID /subject/ SUBJECT
Replace the following:
-
PROJECT_NUMBER
: the project number -
POOL_ID
: the workload pool ID -
SUBJECT
: the individual subject mapped from your IdP—for example,administrator@example.com
By group
principalSet://iam.googleapis.com/projects/ PROJECT_NUMBER /locations/global/workloadIdentityPools/ POOL_ID /group/ GROUP
Replace the following:
-
PROJECT_NUMBER
: the project number -
WORKLOAD_POOL_ID
: the workload pool ID -
GROUP
: the group mapped from your IdP—for example:administrator-group@example.com
By attribute
principalSet://iam.googleapis.com/projects/ PROJECT_NUMBER /locations/global/workloadIdentityPools/ POOL_ID /attribute. ATTRIBUTE_NAME / ATTRIBUTE_VALUE
Replace the following:
-
PROJECT_NUMBER
: the project number -
WORKLOAD_POOL_ID
: the workload pool ID -
ATTRIBUTE_NAME
: one of the attributes that was mapped from your IdP -
ATTRIBUTE_VALUE
: the value of the attribute
By pool
<principalSet://iam.googleapis.com/projects/ PROJECT_NUMBER /locations/global/workloadIdentityPools/ POOL_ID /*
Replace the following:
-
PROJECT_NUMBER
: the project number -
WORKLOAD_POOL_ID
: the workload pool ID
-
-
In Select a role, select the Workload Identity User role (
roles/iam.workloadIdentityUser
). -
To save the configuration, click Save.
-
gcloud
To use the gcloud CLI to grant the role Workload Identity User ( roles/iam.workloadIdentityUser
)
to external identities that meet certain criteria, run the following
command.
By subject
gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \ --role=roles/iam.workloadIdentityUser \ --member="principal://iam.googleapis.com/projects/ PROJECT_NUMBER /locations/global/workloadIdentityPools/ POOL_ID /subject/ SUBJECT "
By group
gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \ --role=roles/iam.workloadIdentityUser \ --member="principalSet://iam.googleapis.com/projects/ PROJECT_NUMBER /locations/global/workloadIdentityPools/ POOL_ID /group/ GROUP "
By attribute
gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \ --role=roles/iam.workloadIdentityUser \ --member="principalSet://iam.googleapis.com/projects/ PROJECT_NUMBER /locations/global/workloadIdentityPools/ POOL_ID /attribute. ATTRIBUTE_NAME / ATTRIBUTE_VALUE "
Replace the following:
-
SERVICE_ACCOUNT_EMAIL
: the email address of the service account -
PROJECT_NUMBER
: the project number . of the project that contains the workload identity pool -
POOL_ID
: the pool ID of the workload identity pool -
SUBJECT
: the expected value for the attribute that you've mapped togoogle.subject
-
GROUP
: the expected value for the attribute that you've mapped togoogle.groups
-
ATTRIBUTE_NAME
: the name of a custom attribute in your attribute mapping -
ATTRIBUTE_VALUE
: the value of the custom attribute in your attribute mapping
Download the configuration
To let your workload access client libraries, you must first download and configure application default credentials (ADC) by doing the following:
-
In the Google Cloud console, go to the Workload Identity Poolspage.
Go to Workload Identity Pools -
In the table, select your pool to go the pool's detail page.
-
Click Grant access.
-
Select Grant access using federated identities (Recommended).
-
To download the Application Default Credential (ADC) so that your workload can access client libraries, do the following:
-
Click Download config.
-
In the Configure your applicationdialog, do the following:
-
In the Providerdrop-down list, select your provider.
-
In OIDC token pathor SAML assertion path, enter the path where the token or assertion is located.
In the Format typedrop-down list, select the format.
-
-
Click Download configuration, and note the path where you saved the file.
-