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, 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

  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 Workload Identity User (roles/iam.workloadIdentityUser) 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.

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. It's best to 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.

    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.

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

  2. To grant access to a federated identity using service account impersonation by using the Google Cloud console or the gcloud CLI, do the following:

    Console

    To use the Google Cloud console to grant IAM roles to a federated identity with service account, do the following:

    1. Create a service account that serves as the identity to impersonate, by doing 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 identity for 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 when you grant IAM access, 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.

    2. To grant access using service account impersonation, 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.

    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 storage buckets add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
    --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 SERVICE_ACCOUNT_EMAIL \
    --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 SERVICE_ACCOUNT_EMAIL \
    --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:

    • 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

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.

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

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