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

If you use Amazon Elastic Kubernetes Service (Amazon EKS) or Azure KubernetesService (AKS), seeConfigure Workload Identity Federation with Kubernetesto learn how to configure Workload Identity Federation for your clusters. Thispage covers only configuring Workload Identity Federation for AWS and AzureVMs.

By using Workload Identity Federation, workloads that run on AWS EC2 andAzure VMs can exchange their environment-specific credentials for short-livedGoogle Cloud Security Token Service tokens.

Environment-specific credentials include the following:

• AWS EC2 instances can use instance profiles to requesttemporary credentials.
• Azure VMs can usemanaged identities to obtain Azure access tokens.

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

Before you begin

• Set up authentication.

  Important: New Amazon EC2 instances useIMDSv2.If your instance uses IMDSv2, you must follow the gcloud CLIinstructions instead of the Google Cloud console instructions. To learnmore, seeAmazon EC2 Instance Metadata Service (IMDSv2) by default.

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

  Install the Google Cloud CLI.

  If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

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

  gcloudauthapplication-defaultlogin

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

  If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

  For more information, see Set up ADC 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 orAWS account.

Configure Workload Identity Federation

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

To start configuring Workload Identity Federation, do the following:

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

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.create permission.Learn how to grant roles.

Go to project selector

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

Verify that billing is enabled for your Google Cloud project.

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

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enable permission.Learn how to grant roles.

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 inprincipal identifiers to uniquely identifyan AWS or Azure user or role.

Optionally, you canmap additional attributes.You can then refer to these additional attributes when granting access toresources.

google.subject=assertion.arnattribute.account=assertion.accountattribute.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

google.subject=assertion.sub.extract('/eid1/c/pub/t/{sub_claim}')

Optionally, define anattribute condition. Attribute conditionsare CEL expressions that can check assertion attributes and target attributes.If the attribute condition evaluates totrue for a given credential, thecredential 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 identitypool and provider:

To provide your workload with access to Google Cloud resources, werecommend that you grant direct resource access to the principal. In this case,the principal is the federated user. Some Google Cloud products haveGoogle Cloud API limitations.If your workload calls an API endpoint that has a limitation, you can insteaduse service account impersonation. In this case, the principal is theGoogle Cloud service account, which acts as the identity. You grant accessto the service account on the resource.

gcloud iam service-accounts add-iam-policy-bindingSERVICE_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-bindingSERVICE_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-bindingSERVICE_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

TheCloud Client Libraries, thegcloud CLI, and Terraform, can automatically obtain externalcredentials, and use these credentials to impersonate a service account. Tolet libraries and tools complete this process, you have to provide a credentialconfiguration 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 \    --sts-location=REGION \    --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 \    --sts-location=REGION \    --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-uriAPPLICATION_ID_URI \    --sts-location=REGION \    --output-file=FILEPATH.json

Use the credential configuration to access Google Cloud

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

1. Initialize an environment variableGOOGLE_APPLICATION_CREDENTIALS and pointit to the credential configuration file:

   Bash

     export GOOGLE_APPLICATION_CREDENTIALS=`pwd`/FILEPATH.json

   whereFILEPATH is the relative path to the credential configuration file.

   PowerShell

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

   whereFILEPATH is the relative path to the credential configuration file.

2. Use a client library or tool that supports Workload Identity Federationand canfind credentials automatically:

   C++

   TheGoogle Cloud Client Libraries for C++support Workload Identity Federation since versionv2.6.0.To use Workload Identity Federation, you must build the client librarieswith version 1.36.0 or later of gRPC.

   Go

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

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

   cd$GOPATH/src/cloud.google.com/gogolist-mgolang.org/x/oauth2

   Java

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

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

   mvndependency:list-DincludeArtifactIds=google-auth-library-oauth2-http

   Node.js

   Client libraries for Node.js support Workload Identity Federation if they use version7.0.2 or later of thegoogle-auth-library package.

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

   npmlistgoogle-auth-library

   When you create aGoogleAuth object, you can specify a project ID, or you canallowGoogleAuth to find the project ID automatically. To find the project IDautomatically, the service account in the configuration file must have theBrowser role (roles/browser), or a role with equivalent permissions, on yourproject. For details, see theREADME for thegoogle-auth-library package.

   Python

   Client libraries for Python support Workload Identity Federation if they use version1.27.0 or later of thegoogle-auth package.

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

   pipshowgoogle-auth

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

   gcloud

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

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

   ReplaceFILEPATH with the path to thecredential configuration file.

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

   Terraform

   TheGoogle Cloud providersupports 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 thegcloud auth login command, as follows:

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

   ReplaceFILEPATH with the path to thecredential configuration file.

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

   If you can't use a client library that supportsWorkload Identity Federation, you canauthenticate programmatically byusing 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 letan 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 normallyinclude in a request to the AWSGetCallerIdentity() endpoint, including a validrequest signature.

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

   AGetCallerIdentity 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 forGetCallerIdentity(),with the body of a standardGetCallerIdentity() request appendedas query parameters. For example,https://sts.amazonaws.com?Action=GetCallerIdentity&Version=2011-06-15.We recommend that you use regional STS endpoints anddesign a reliable infrastructure for your workloads.For more information, seeRegional 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 theurl field; for example,sts.amazonaws.com.
     • x-amz-date: The time you will send the request, formatted as anISO 8601 Basic string. This value is typically set to the current time and isused to help prevent replay attacks.
     • x-goog-cloud-target-resource: The full resource name of theidentity provider without ahttps: 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 areusingtemporary security credentials.

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

   importjsonimporturllibimportboto3frombotocore.authimportSigV4Authfrombotocore.awsrequestimportAWSRequestdefcreate_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.htmlSigV4Auth(boto3.Session().get_credentials(),"sts","us-east-1").add_auth(request)# Create token from signed request.token={"url":request.url,"method":request.method,"headers":[]}forkey,valueinrequest.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)))defmain()->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"

   WhereTOKEN is theURL encodedGetCallerIdentity token that was generated by the script.

   Azure

   Connect to an Azure VM that has anassigned managed identity andobtain 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 thejq 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_tokenWrite-Host $SubjectToken

   WhereAPP_ID_URI is theApplication ID URIof the application that you'veconfigured for Workload Identity Federation.

2. Use theSecurity Token Service API to exchange the credential againsta 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_tokenWrite-Host $StsToken

   Replace the following values:

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

   To use regional Security Token Service endpoints, replacehttps://sts.googleapis.com/v1/token with the following:

    https://sts.REGION.rep.googleapis.com/v1/token

   ReplaceREGION with aGoogle Cloud location,for example,us-central1 oreurope-west4.

   Note: The audience must not include ahttps: scheme.

3. If you use service account impersonation, use the token from theSecurity Token Service to invoke thegenerateAccessToken methodof theIAM Service Account Credentials APIto 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)).tokenWrite-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, seeUnderstanding 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)).accessTokenWrite-Host $Token

Replace the following:

• SERVICE_ACCOUNT_EMAIL: the email address of the service account.

What's next

• Read more aboutWorkload Identity Federation.
• Learn aboutbest practices for using Workload Identity Federation.
• See how you canmanage workload identity pools and providers.