Download credential configuration and grant access

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.

1. In the Google Cloud console, go to the Cloud Storage Buckets page.
   

   Go to Buckets

2. In the list of buckets, click the name of the bucket for which you want to grant the role.

3. Select the Permissions tab near the top of the page.

4. Click the Grant access button.

   The Add principals dialog appears.

5. In the New principals field, 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, [e-mail]

   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: [e-mail]

   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

6. Select a role (or roles) from the Select a role drop-down menu. The roles you select appear in the pane with a short description of the permissions they grant.

7. Click Save.

gcloud

To use the gcloud CLI to grant IAM roles on a resource in a project, do the following:

1. 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\)
   

2. 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 to google.subject
   • GROUP: the expected value for the attribute that you've mapped to google.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.

   Note: You must use the project number, not the project ID, in the member identifier.

Service account impersonation

1. To create a service account for the external workload, do the following:

   1. Enable the IAM, Security Token Service, and Service Account Credentials APIs.

      Enable the APIs

   2. 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.

   3. Grant the service account access to resources that you want external identities to access.

   4. Grant the Workload Identity User role (roles/iam.workloadIdentityUser) to the service account.

2. 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

1. To grant access using service account impersonation for a service account in the same project, do the following:

   1. Go to the Workload Identity Pools page.

      Go to Workload Identity Pools

   2. Select Grant access.

   3. In the Grant access to service account dialog, select Grant access using Service Account impersonation.

   4. In the Service accounts list, select the service account for the external identities to impersonate, and do the following:

   5. 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 name list, select the attribute that you want to filter on.

      • In the Attribute value field, enter the expected value of the attribute; for example, if you use an attribute mapping google.subject=assertion.sub, set Attribute name to subject and Attribute value to the value of the sub claim in tokens that are issued by your external identity provider.

   6. To save the configuration, click Save and then Dismiss.

Service account in a different project

Note: Service accounts from different projects won't appear in the "CONNECTED SERVICE ACCOUNTS" section of your Workload Identity Pool.

1. To grant access using service account impersonation for a service account in a different project, do the following:

   1. Go to the Service Accounts page.

      Go to Service Accounts

   2. Select the service account that you want to impersonate.

   3. Click Manage access.

   4. Click Add principal.

   5. In the New principal field, 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, [e-mail]

      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: [e-mail]

      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

   6. In Select a role, select the Workload Identity User role (roles/iam.workloadIdentityUser).

   7. 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 to google.subject
• GROUP: the expected value for the attribute that you've mapped to google.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

Note: You must use the project number, not the project ID, in the member identifier.

Download the configuration

To let your workload access client libraries, you must first download and configure application default credentials (ADC) by doing the following:

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

   Go to Workload Identity Pools

2. In the table, select your pool to go the pool's detail page.

3. Click Grant access.

4. Select Grant access using federated identities (Recommended).

5. To download the Application Default Credential (ADC) so that your workload can access client libraries, do the following:

   1. Click Download config.

   2. In the Configure your application dialog, do the following:

      1. In the Provider drop-down list, select your provider.

      2. In OIDC token path or SAML assertion path, enter the path where the token or assertion is located.

      In the Format type drop-down list, select the format.

   3. Click Download configuration, and note the path where you saved the file.