Configure Workload Identity Federation with AWS or Azure VMs (original) (raw)

Skip to main content

Configure Workload Identity Federation with AWS or Azure VMs

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

If you use Amazon Elastic Kubernetes Service (Amazon EKS) or Azure Kubernetes Service (AKS), see Configure Workload Identity Federation with Kubernetesto learn how to configure Workload Identity Federation for your clusters. This page covers only configuring Workload Identity Federation for AWS and Azure VMs.

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

Environment-specific credentials include the following:

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

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:
gcloud auth application-default login
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 or AWS account.

AWS

You don't need to make any configuration changes in your AWS account.

After you configure a workload identity pool to trust your AWS account, you can let AWS usersand AWS rolesuse permanent or temporary AWS security credentials to obtain short-lived Google Cloud credentials.

Azure

You must create a new Microsoft Entra ID applicationin your Microsoft Entra ID tenant and configure it so that it can be used for Workload Identity Federation.

After you configure a workload identity pool to trust the application, Azure users and service principals can request access tokens for this application and exchange these access tokens against short-lived Google Cloud credentials.

To create the application, do the following:

  1. Create a Microsoft Entra ID application and service principal.
  2. Set an Application ID URI for the application. You can use the default Application ID URI (APPID) or specify a custom URI.
    You need the Application ID URI later when you configure the workload identity pool provider.

To let an application obtain access tokens for the Microsoft Entra ID application, you can use managed identities:

  1. Create a managed identity. Note the Object ID of the managed identity. You need it later when you configure impersonation.
  2. Assign the managed identityto a virtual machine or another resource that runs your application.

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:

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

Go to project selector

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

AWS

Your attribute mapping can use theresponse fields for GetCallerIdentityas source attributes. These fields include the following:

If your application runs on an Amazon Elastic Compute Cloud (EC2) instance with an attached role, you can use the following attribute mapping:

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}')

The mapping does the following:

Using this mapping, you can grant access to:

Azure

Your attribute mappings can use theclaims embedded in Azure access tokens, including custom claims, as source attributes. In most cases, it's best to use the sub claim as subject identifier:

google.subject=assertion.sub

When the sub claim surpasses the 127-character limit for google.subject, we recommend that you use the extract functionto derive a subject identifier—for example:

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

For an access token issued to a managed identity, the sub claim contains the Object ID of the managed identity. If you use a different claim, make sure that the claim is unique and can't be reassigned.

If you're unsure about the list of claims you can reference, do the following:

  1. Connect to an Azure VM that has an assigned managed identity.
  2. Obtain an access token from the Azure Instance Metadata Service (IMDS):

Bash

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
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
Replace APP_ID_URI with the Application ID URIof the application that you've configured for Workload Identity Federation. 3. In a web browser, go to https://jwt.ms/ and paste the access token into the field. 4. Click Claims to view the list of claims embedded in the access token.

For service identities, it's typically not necessary to create a mapping for google.groups or any custom attributes.

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.

AWS

You can use an attribute condition to restrict which IAM users and roles can use Workload Identity Federation to obtain short-lived Google Cloud tokens.

For example, the following condition restricts access to AWS roles and disallows other IAM identifiers:

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

Azure

You can use an attribute condition to restrict which users and service principals can use Workload Identity Federation to obtain short-lived Google Cloud tokens. Alternatively, you can configure your Microsoft Entra ID application to useapp role assignments.

Create the workload identity pool and provider

Required roles

To get the permissions that you need to configure Workload Identity Federation, ask your administrator to grant you the following IAM roles on the project:

For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Alternatively, the IAM Owner (roles/owner) basic role also includes permissions to configure identity federation. You should not grant basic roles in a production environment, but you can grant them in a development or test environment.

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

Console

  1. In the Google Cloud console, go to the New workload provider and poolpage.
    Go to New workload provider and pool
  2. In the Create an identity pool section, enter the following:
    • Name: Name for the pool. The name is also used as the pool ID. You can't change the pool ID later.
    • Description: Text that describes the purpose of the pool.
  3. Click Continue.
  4. Configure provider settings:

AWS

Configure the following provider settings:

Azure

Configure the following provider settings:

  1. Click Continue.
  2. In the Configure provider attributes section, add the attribute mappings that you've identified previously.
  3. In the Attribute conditions section, enter theattribute conditionthat you identified previously. Leave the field blank if you don't have an attribute condition.
  4. Click Save to create the workload identity pool and provider.

gcloud

  1. Create a new workload identity pool:
    gcloud iam workload-identity-pools create POOL_ID \
    --location="global" \
    --description="DESCRIPTION" \
    --display-name="DISPLAY_NAME"
    Replace the following:
    • POOL_ID: the unique ID for the pool.
    • DISPLAY_NAME: the name of the pool.
    • DESCRIPTION: the description of the pool. This description appears when granting access to pool identities.
  2. Add a workload identity pool provider:

AWS

To create the workload identity pool provider for AWS, execute the following command:
gcloud iam workload-identity-pools providers create-aws PROVIDER_ID \
--location="global" \
--workload-identity-pool="POOL_ID" \
--account-id="ACCOUNT_ID" \
--attribute-mapping="MAPPINGS" \
--attribute-condition="CONDITIONS"
Replace the following:

Azure

To create the workload identity pool provider for Azure, execute the following command:
gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
--location="global" \
--workload-identity-pool="POOL_ID" \
--issuer-uri="ISSUER_URI" \
--allowed-audiences="APPLICATION_ID_URI" \
--attribute-mapping="MAPPINGS" \
--attribute-condition="CONDITIONS"
Replace the following:

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 haveGoogle 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:

By group

principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP

Replace the following:

By attribute

principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE

Replace the following:

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

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.
      Roles required to enable APIs
      To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.
      Enable the APIs
    2. Create a service accountthat 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 accessto resources that you want external identities to access.
  2. To let the federated identity impersonate the service account, do the following:

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, selectGrant 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, selectOnly 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, setAttribute name to subject and Attribute valueto the value of the sub claim in tokens that are issued by your external identity provider.
    6. To save the configuration, click Save and thenDismiss.

Service account in a different project

  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 followingprincipal identifiersfor 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
    6. In Select a role, select the Workload Identity User role (roles/iam.workloadIdentityUser).
    7. To save the configuration, click Save.

gcloud

To grant the Workload Identity User role (roles/iam.workloadIdentityUser) to a federated principal or principal set, run the following command. To learn more about Workload Identity Federation principal identifiers, see Principal types.

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:

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:

To create a credential configuration file, do the following:

Console

To download a credential configuration file in the Google Cloud console, do the following:

  1. In the Google Cloud console, go to the Workload Identity Poolspage.
    Go to Workload Identity Pools
  2. Find the workload identity pool for the IdP that you want to use and click it.
  3. If you chose to use direct resource access, do the following:
    1. Click Grant access.
    2. Select Grant access using federated identities (Recommended).
    3. Click Download.
    4. Continue with instructions to Configure your application dialog, later in this procedure.
  4. If you chose to use service account impersonation, do the following:
    1. Select Connected service accounts.
    2. Find the service account you want to use and clickDownload.
    3. Continue with instructions to Configure your application dialog, later in this procedure.
  5. In the Configure your application dialog, select the provider that contains the external identities.
  6. Provide the following additional settings:

AWS

No additional settings required.

Azure

Application ID URL: Application ID URI of the Azure application 7. Select Download configto download the credential configuration file, then click Dismiss.

If you want to use the Security Token Service regional endpoints—for example,https://sts.us-central1.rep.googleapis.com, refer toUsing regional Security Token Service endpoints for better reliability.

gcloud

To create a credential configuration file by usinggcloud iam workload-identity-pools create-cred-config, do the following:

AWS

To create a credential configuration file that lets the library obtain an access token from EC2 instance metadata, 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

Replace the following:

If you useAWS IMDSv2, an additional flag --enable-imdsv2 needs to be added to thegcloud iam workload-identity-pools create-cred-configcommand:

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

If using the AWS metadata server isn't an option, you can provide AWS security credentials through the following AWS environment variables:

The gcloud CLI and libraries use these AWS environment variables when the AWS metadata server is unavailable.

Azure

Create a credential configuration file that lets the library obtain an access token from the Azure Instance Metadata Service (IMDS):

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
--sts-location=REGION
--output-file=FILEPATH.json

Replace the following:

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

TheGoogle Cloud Client Libraries for C++support Workload Identity Federation since versionv2.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 thecom.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 thegoogle-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 theREADME 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 thegoogle-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 theGOOGLE_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 theuser guide for the google-auth package.

gcloud

To authenticate using Workload Identity Federation, use thegcloud 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 inversion 363.0.0 and later versions of the gcloud CLI.

Terraform

The Google 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
Replace FILEPATH with the path to the credential 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 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 aGetCallerIdentity 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:

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:
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 identityand obtain an access tokenfrom 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 URIof the application that you'veconfigured 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:

  1. If you use service account impersonation, use the token from the Security Token Service to invoke the generateAccessToken methodof the IAM 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.

Bash

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

PowerShell

$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:

Tokens for other platforms

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

Bash

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

PowerShell

$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:

What's next

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-09 UTC.