Configure Workload Identity Federation with AWS or Azure

This guide describes how to use Workload Identity Federation to let AWS and Azure workloads authenticate to Google Cloud without a service account key.

Using Workload Identity Federation, workloads that run on AWS EC2 and Azure can exchange their environment-specific credentials for short-lived Google Cloud Security Token Service tokens.

Environment-specific credentials include the following:

• AWS EC2 instances can use instance profiles to request temporary credentials.
• Azure VMs can use managed identities to obtain Azure access tokens.

By setting up Workload Identity Federation, you can let these workloads exchange these environment-specific credentials against short-lived Google Cloud credentials. Workloads can use these short-lived credentials to access Google Cloud APIs.

Before you begin

• Set up authentication.

  Select the tab for how you plan to use the samples on this page:

  Console

  When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

  gcloud

  In the Google Cloud console, activate Cloud Shell.

  Activate Cloud Shell

  At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  Python

  To use the Python samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.

  1. Install the Google Cloud CLI.

  2. To initialize the gcloud CLI, run the following command:

     gcloud init

  3. If you're using a local shell, then create local authentication credentials for your user account:

     gcloud auth application-default login

     You don't need to do this if you're using Cloud Shell.

  For more information, see Set up authentication for a local development environment in the Google Cloud authentication documentation.

Prepare your external identity provider

You only need to perform these steps once for each Microsoft Entra ID tenant or AWS account.

Configure Workload Identity Federation

You only need to perform these steps once per AWS account or Microsoft Entra ID tenant. You can then use the same workload identity pool and provider for multiple workloads and across multiple Google Cloud projects.

To start configuring Workload Identity Federation, do the following:

1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Go to project selector

It's best to use a dedicated project to manage workload identity pools and providers.

2. Make sure that billing is enabled for your Google Cloud project.

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

Enable the APIs

Define an attribute mapping and condition

The environment-specific credentials of your AWS or Azure workload contain multiple attributes, and you must decide which attribute you want to use as subject identifier (google.subject) in Google Cloud.

Google Cloud uses the subject identifier in Cloud Audit Logs and in principal identifiers to uniquely identify an AWS or Azure user or role.

Optionally, you can map additional attributes. You can then refer to these additional attributes when granting access to resources.

google.subject=assertion.arn
attribute.account=assertion.account
attribute.aws_role=assertion.arn.extract('assumed-role/{role}/')
attribute.aws_ec2_instance=assertion.arn.extract('assumed-role/{role_and_session}').extract('/{session}')

google.subject=assertion.sub

Optionally, define an attribute condition. Attribute conditions are CEL expressions that can check assertion attributes and target attributes. If the attribute condition evaluates to true for a given credential, the credential is accepted. Otherwise, the credential is rejected.

assertion.arn.startsWith('arn:aws:sts::AWS_ACCOUNT_ID:assumed-role/')

Create the workload identity pool and provider

You now have collected all of the information that you need to create a workload identity pool and provider:

Authenticate a workload

You must perform these steps once per workload.

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.

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"

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"

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"

Download or create a credential configuration

The Cloud Client Libraries, the gcloud CLI, and Terraform, can automatically obtain external credentials, and use these credentials to impersonate a service account. To let libraries and tools complete this process, you have to provide a credential configuration file. This file defines the following:

• Where to obtain external credentials from
• Which workload identity pool and provider to use
• Which service account to impersonate

To create a credential configuration file, do the following:

gcloud iam workload-identity-pools create-cred-config \
    projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \
    --service-account=SERVICE_ACCOUNT_EMAIL \
    --service-account-token-lifetime-seconds=SERVICE_ACCOUNT_TOKEN_LIFETIME \
    --aws \
    --output-file=FILEPATH.json

gcloud iam workload-identity-pools create-cred-config \
    projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \
    --service-account=SERVICE_ACCOUNT_EMAIL \
    --aws \
    --enable-imdsv2 \
    --output-file=FILEPATH.json

gcloud iam workload-identity-pools create-cred-config \
    projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \
    --service-account=SERVICE_ACCOUNT_EMAIL \
    --service-account-token-lifetime-seconds=SERVICE_ACCOUNT_TOKEN_LIFETIME \
    --azure \
    --app-id-uri APPLICATION_ID_URI \
    --output-file=FILEPATH.json

Use the credential configuration to access Google Cloud

To let tools and client libraries use your credential configuration, do the following in your AWS or Azure environment:

1. Initialize an environment variable GOOGLE_APPLICATION_CREDENTIALS and point it to the credential configuration file:

   Bash

     export GOOGLE_APPLICATION_CREDENTIALS=`pwd`/FILEPATH.json
     

   where FILEPATH is the relative path to the credential configuration file.

   PowerShell

     $env:GOOGLE_APPLICATION_CREDENTIALS = Resolve-Path 'FILEPATH.json'
     

   where FILEPATH is the relative path to the credential configuration file.

2. Use a client library or tool that supports Workload Identity Federation and can find credentials automatically:

   C++

   The Google Cloud Client Libraries for C++ support Workload Identity Federation since version v2.6.0. To use Workload Identity Federation, you must build the client libraries with version 1.36.0 or later of gRPC.

   Go

   Client libraries for Go support Workload Identity Federation if they use version v0.0.0-20210218202405-ba52d332ba99 or later of the golang.org/x/oauth2 module.

   To check which version of this module your client library uses, run the following commands:

   cd $GOPATH/src/cloud.google.com/go
   go list -m golang.org/x/oauth2
   

   Java

   Client libraries for Java support Workload Identity Federation if they use version 0.24.0 or later of the com.google.auth:google-auth-library-oauth2-http artifact.

   To check which version of this artifact your client library uses, run the following Maven command in your application directory:

   mvn dependency:list -DincludeArtifactIds=google-auth-library-oauth2-http
   

   Node.js

   Client libraries for Node.js support Workload Identity Federation if they use version 7.0.2 or later of the google-auth-library package.

   To check which version of this package your client library uses, run the following command in your application directory:

   npm list google-auth-library
   

   When you create a GoogleAuth object, you can specify a project ID, or you can allow GoogleAuth to find the project ID automatically. To find the project ID automatically, the service account in the configuration file must have the Browser role (roles/browser), or a role with equivalent permissions, on your project. For details, see the README for the google-auth-library package.

   Python

   Client libraries for Python support Workload Identity Federation if they use version 1.27.0 or later of the google-auth package.

   To check which version of this package your client library uses, run the following command in the environment where the package is installed:

   pip show google-auth
   

   To specify a project ID for the authentication client, you can set the GOOGLE_CLOUD_PROJECT environment variable, or you can allow the client to find the project ID automatically. To find the project ID automatically, the service account in the configuration file must have the Browser role (roles/browser), or a role with equivalent permissions, on your project. For details, see the user guide for the google-auth package.

   gcloud

   To authenticate using Workload Identity Federation, use the gcloud auth login command:

   gcloud auth login --cred-file=FILEPATH.json
   

   Replace FILEPATH with the path to the credential configuration file.

   Support for Workload Identity Federation in gcloud CLI is available in version 363.0.0 and later versions of the gcloud CLI.

   Terraform

   The Google Cloud provider supports Workload Identity Federation if you use version 3.61.0 or later:

   terraform {
     required_providers {
       google = {
         source  = "hashicorp/google"
         version = "~> 3.61.0"
       }
     }
   }
   

   bq

   To authenticate using Workload Identity Federation, use the gcloud auth login command, as follows:

   gcloud auth login --cred-file=FILEPATH.json
   

   Replace FILEPATH with the path to the credential configuration file.

   Support for Workload Identity Federation in bq is available in version 390.0.0 and later versions of the gcloud CLI.

   If you can't use a client library that supports Workload Identity Federation, you can authenticate programmatically by using the REST API.

Advanced scenarios

Authenticate a workload using the REST API

If you can't use the client libraries, you can follow these steps to let an external workload obtain a short-lived access token by using the REST API:

1. Obtain credentials from your external IdP:

   AWS

   Create a JSON document that contains the information that you would normally include in a request to the AWS GetCallerIdentity() endpoint, including a valid request signature.

   Workload Identity Federation refers to this JSON document as a GetCallerIdentity token. The token lets Workload Identity Federation verify the identity without revealing the AWS secret access key.

   A GetCallerIdentity token looks similar to the following:

   {
     "url": "https://sts.amazonaws.com?Action=GetCallerIdentity&Version=2011-06-15",
     "method": "POST",
     "headers": [
       {
         "key": "Authorization",
         "value" : "AWS4-HMAC-SHA256 Credential=AKIASOZTBDV4D7ABCDEDF/20200228/us-east-1/sts/aws4_request, SignedHeaders=host;x-amz-date,Signature=abcedefdfedfd"
       },
       {
         "key": "host",
         "value": "sts.amazonaws.com"
       },
       {
         "key": "x-amz-date",
         "value": "20200228T225005Z"
       },
       {
         "key": "x-goog-cloud-target-resource",
         "value": "//iam.googleapis.com/projects/12345678/locations/global/workloadIdentityPools/my-pool/providers/my-aws-provider"
       },
       {
         "key": "x-amz-security-token",
         "value": "GizFWJTqYX...xJ55YoJ8E9HNU="
       }
     ]
   }
   

   The token contains the following fields:

   • url: The URL of the AWS STS endpoint for GetCallerIdentity(), with the body of a standard GetCallerIdentity() request appended as query parameters. For example, https://sts.amazonaws.com?Action=GetCallerIdentity&Version=2011-06-15. We recommend that you use regional STS endpoints and design a reliable infrastructure for your workloads. For more information, see Regional AWS STS endpoints.
   • method: The HTTP request method: POST.
   • headers: The HTTP request headers, which must include:
     • Authorization: The request signature.
     • host: The hostname of the url field; for example, sts.amazonaws.com.
     • x-amz-date: The time you will send the request, formatted as an ISO 8601 Basic string. This value is typically set to the current time and is used to help prevent replay attacks.
     • x-goog-cloud-target-resource: The full resource name of the identity provider without a https: prefix. For example:

       //iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID
       

     • x-amz-security-token: Session token. Only required if you are using temporary security credentials.

   The following example creates a URL-encoded GetCallerIdentity token. Extract the URL-encoded token for later use. It also creates a human-readable token just for your reference:

   import json
   import urllib
   
   import boto3
   from botocore.auth import SigV4Auth
   from botocore.awsrequest import AWSRequest
   
   
   def create_token_aws(project_number: str, pool_id: str, provider_id: str) -> None:
       # Prepare a GetCallerIdentity request.
       request = AWSRequest(
           method="POST",
           url="https://sts.amazonaws.com/?Action=GetCallerIdentity&Version=2011-06-15",
           headers={
               "Host": "sts.amazonaws.com",
               "x-goog-cloud-target-resource": f"//iam.googleapis.com/projects/{project_number}/locations/global/workloadIdentityPools/{pool_id}/providers/{provider_id}",
           },
       )
   
       # Set the session credentials and Sign the request.
       # get_credentials loads the required credentials as environment variables.
       # Refer:
       # https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html
       SigV4Auth(boto3.Session().get_credentials(), "sts", "us-east-1").add_auth(request)
   
       # Create token from signed request.
       token = {"url": request.url, "method": request.method, "headers": []}
       for key, value in request.headers.items():
           token["headers"].append({"key": key, "value": value})
   
       # The token lets workload identity federation verify the identity without revealing the AWS secret access key.
       print("Token:\n%s" % json.dumps(token, indent=2, sort_keys=True))
       print("URL encoded token:\n%s" % urllib.parse.quote(json.dumps(token)))
   
   
   def main() -> None:
       # TODO(Developer): Replace the below credentials.
       # project_number: Google Project number (not the project id)
       project_number = "my-project-number"
       pool_id = "my-pool-id"
       provider_id = "my-provider-id"
   
       create_token_aws(project_number, pool_id, provider_id)
   
   
   if __name__ == "__main__":
       main()

   Initialize the following variables:

   Bash

   SUBJECT_TOKEN_TYPE="urn:ietf:params:aws:token-type:aws4_request"
   SUBJECT_TOKEN=TOKEN
   

   PowerShell

   $SubjectTokenType = "urn:ietf:params:aws:token-type:aws4_request"
   $SubjectToken = "TOKEN"
   

   Where TOKEN is the URL encoded GetCallerIdentity token that was generated by the script.

   Azure

   Connect to an Azure VM that has an assigned managed identity and obtain an access token from the Azure Instance Metadata Service (IMDS):

   Bash

   SUBJECT_TOKEN_TYPE="urn:ietf:params:oauth:token-type:jwt"
   SUBJECT_TOKEN=$(curl \
     "http://169.254.169.254/metadata/identity/oauth2/token?resource=APP_ID_URI&api-version=2018-02-01" \
     -H "Metadata: true" | jq -r .access_token)
   echo $SUBJECT_TOKEN
   

   This command uses the jq tool. jq is available by default in Cloud Shell.

   PowerShell

   $SubjectTokenType = "urn:ietf:params:oauth:token-type:jwt"
   $SubjectToken = (Invoke-RestMethod `
     -Uri "http://169.254.169.254/metadata/identity/oauth2/token?resource=APP_ID_URI&api-version=2018-02-01" `
     -Headers @{Metadata="true"}).access_token
   Write-Host $SubjectToken
   

   Where APP_ID_URI is the Application ID URI of the application that you've configured for Workload Identity Federation.

2. Use the Security Token Service API to exchange the credential against a short-lived access token:

   Bash

   STS_TOKEN=$(curl https://sts.googleapis.com/v1/token \
       --data-urlencode "audience=//iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID" \
       --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
       --data-urlencode "requested_token_type=urn:ietf:params:oauth:token-type:access_token" \
       --data-urlencode "scope=https://www.googleapis.com/auth/cloud-platform" \
       --data-urlencode "subject_token_type=$SUBJECT_TOKEN_TYPE" \
       --data-urlencode "subject_token=$SUBJECT_TOKEN" | jq -r .access_token)
   echo $STS_TOKEN
   

   PowerShell

   [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.SecurityProtocolType]::Tls12
   $StsToken = (Invoke-RestMethod `
       -Method POST `
       -Uri "https://sts.googleapis.com/v1/token" `
       -ContentType "application/json" `
       -Body (@{
           "audience"           = "//iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID"
           "grantType"          = "urn:ietf:params:oauth:grant-type:token-exchange"
           "requestedTokenType" = "urn:ietf:params:oauth:token-type:access_token"
           "scope"              = "https://www.googleapis.com/auth/cloud-platform"
           "subjectTokenType"   = $SubjectTokenType
           "subjectToken"       = $SubjectToken
       } | ConvertTo-Json)).access_token
   Write-Host $StsToken
   

   Replace the following values:

   • PROJECT_NUMBER: Project number of the project that contains the workload identity pool
   • POOL_ID: ID of the workload identity pool
   • PROVIDER_ID: ID of the workload identity pool provider

3. If you use service account impersonation, use the token from the Security Token Service to invoke the generateAccessToken method of the IAM Service Account Credentials API to obtain an access token.

Tokens for Cloud Run services

When accessing a Cloud Run service, you must use an ID token.

TOKEN=$(curl -0 -X POST https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/SERVICE_ACCOUNT_EMAIL:generateIdToken \
    -H "Content-Type: text/json; charset=utf-8" \
    -H "Authorization: Bearer $STS_TOKEN" \
    -d @- <<EOF | jq -r .token
    {
        "audience": "SERVICE_URL"
    }
EOF
)
echo $TOKEN

$Token = (Invoke-RestMethod `
    -Method POST `
    -Uri "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/SERVICE_ACCOUNT_EMAIL:generateIdToken" `
    -Headers @{ "Authorization" = "Bearer $StsToken" } `
    -ContentType "application/json" `
    -Body (@{
        "audience" = "SERVICE_URL"
    } | ConvertTo-Json)).token
Write-Host $Token

Replace the following:

• SERVICE_ACCOUNT_EMAIL: the email address of the service account.
• SERVICE_URL: the URL of the service—for example, https://my-service-12345-us-central1.run.app. You can also set it to your custom service endpoint. For more information, see Understanding custom audiences.

Tokens for other platforms

When accessing another service, you must use an access token.

TOKEN=$(curl -0 -X POST https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/SERVICE_ACCOUNT_EMAIL:generateAccessToken \
    -H "Content-Type: text/json; charset=utf-8" \
    -H "Authorization: Bearer $STS_TOKEN" \
    -d @- <<EOF | jq -r .accessToken
    {
        "scope": [ "https://www.googleapis.com/auth/cloud-platform" ]
    }
EOF
)
echo $TOKEN

$Token = (Invoke-RestMethod `
    -Method POST `
    -Uri "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/SERVICE_ACCOUNT_EMAIL:generateAccessToken" `
    -Headers @{ "Authorization" = "Bearer $StsToken" } `
    -ContentType "application/json" `
    -Body (@{
        "scope" = , "https://www.googleapis.com/auth/cloud-platform"
    } | ConvertTo-Json)).accessToken
Write-Host $Token

Replace the following:

• SERVICE_ACCOUNT_EMAIL: the email address of the service account.

What's next

• Read more about Workload Identity Federation.
• Learn about best practices for using Workload Identity Federation.
• See how you can manage workload identity pools and providers.