Get an ID token

This page describes some ways to acquire a Google-signed OpenID Connect (OIDC) ID token.

You need a Google-signed ID token for the following authentication use cases:

For information about ID token contents and lifetimes, see ID tokens .

ID tokens have a specific service or application that they can be used for, specified by the value of their aud claim. This document uses the term target service to refer to the service or application that the ID token can be used to authenticate to.

When you get the ID token, you can include it in an Authorization header in the request to the target service.

Methods for getting an ID token

There are various ways to get an ID token. This page describes the following methods:

Get an ID token from the metadata server
Use a connecting service to generate an ID token
Generate an ID token by impersonating a service account
Generate a generic ID token for development with Cloud Run and Cloud Run functions

If you need an ID token to be accepted by an application not hosted on Google Cloud, you can probably use these methods. However, you should determine what ID token claims the application requires.

Get an ID token from the metadata server

When your code is running on a resource that can have a service account attached to it , the metadata server for the associated service can usually provide an ID token. The metadata server generates ID tokens for the attached service account. You cannot get an ID token based on user credentials from the metadata server.

You can get an ID token from the metadata server when your code is running on the following Google Cloud services:

To retrieve an ID token from the metadata server, you query the identity endpoint for the service account, as shown in this example.

curl

Replace AUDIENCE with the URI for the target service, for example http://www.example.com .

curl -H "Metadata-Flavor: Google" \
  'http://metadata/computeMetadata/v1/instance/service-accounts/default/identity?audience= AUDIENCE 
'

PowerShell

Replace AUDIENCE with the URI for the target service, for example http://www.example.com .

$value = (Invoke-RestMethod `
  -Headers @{'Metadata-Flavor' = 'Google'} `
  -Uri "http://metadata/computeMetadata/v1/instance/service-accounts/default/identity?audience= AUDIENCE 
")
$value

Java

To run this code sample, you must install the Auth Client Library for Java .

  import 
  
 com.google.auth.oauth2. GoogleCredentials 
 
 ; 
 import 
  
 com.google.auth.oauth2. IdTokenCredentials 
 
 ; 
 import 
  
 com.google.auth.oauth2. IdTokenProvider 
 
 ; 
 import 
  
 com.google.auth.oauth2. IdTokenProvider 
. Option 
 
 ; 
 import 
  
 java.io.IOException 
 ; 
 import 
  
 java.security.GeneralSecurityException 
 ; 
 import 
  
 java.util.Arrays 
 ; 
 public 
  
 class 
 IdTokenFromMetadataServer 
  
 { 
  
 public 
  
 static 
  
 void 
  
 main 
 ( 
 String 
 [] 
  
 args 
 ) 
  
 throws 
  
 IOException 
 , 
  
 GeneralSecurityException 
  
 { 
  
 // TODO(Developer): Replace the below variables before running the code. 
  
 // The url or target audience to obtain the ID token for. 
  
 String 
  
 url 
  
 = 
  
 "https://example.com" 
 ; 
  
 getIdTokenFromMetadataServer 
 ( 
 url 
 ); 
  
 } 
  
 // Use the Google Cloud metadata server to create an identity token and add it to the 
  
 // HTTP request as part of an Authorization header. 
  
 public 
  
 static 
  
 void 
  
 getIdTokenFromMetadataServer 
 ( 
 String 
  
 url 
 ) 
  
 throws 
  
 IOException 
  
 { 
  
 // Construct the GoogleCredentials object which obtains the default configuration from your 
  
 // working environment. 
  
  GoogleCredentials 
 
  
 googleCredentials 
  
 = 
  
  GoogleCredentials 
 
 . 
  getApplicationDefault 
 
 (); 
  
  IdTokenCredentials 
 
  
 idTokenCredentials 
  
 = 
  
  IdTokenCredentials 
 
 . 
 newBuilder 
 () 
  
 . 
  setIdTokenProvider 
 
 (( 
  IdTokenProvider 
 
 ) 
  
 googleCredentials 
 ) 
  
 . 
  setTargetAudience 
 
 ( 
 url 
 ) 
  
 // Setting the ID token options. 
  
 . 
  setOptions 
 
 ( 
 Arrays 
 . 
 asList 
 ( 
  Option 
 
 . 
 FORMAT_FULL 
 , 
  
  Option 
 
 . 
 LICENSES_TRUE 
 )) 
  
 . 
 build 
 (); 
  
 // Get the ID token. 
  
 // Once you've obtained the ID token, you can use it to make an authenticated call to the 
  
 // target audience. 
  
 String 
  
 idToken 
  
 = 
  
 idTokenCredentials 
 . 
  refreshAccessToken 
 
 (). 
 getTokenValue 
 (); 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 "Generated ID token." 
 ); 
  
 } 
 }

Go

  import 
  
 ( 
  
 "context" 
  
 "fmt" 
  
 "io" 
  
 "golang.org/x/oauth2/google" 
  
 "google.golang.org/api/idtoken" 
  
 "google.golang.org/api/option" 
 ) 
 // getIdTokenFromMetadataServer uses the Google Cloud metadata server environment 
 // to create an identity token and add it to the HTTP request as part of an Authorization header. 
 func 
  
 getIdTokenFromMetadataServer 
 ( 
 w 
  
 io 
 . 
 Writer 
 , 
  
 url 
  
 string 
 ) 
  
 error 
  
 { 
  
 // url := "http://www.example.com" 
  
 ctx 
  
 := 
  
 context 
 . 
 Background 
 () 
  
 // Construct the GoogleCredentials object which obtains the default configuration from your 
  
 // working environment. 
  
 credentials 
 , 
  
 err 
  
 := 
  
 google 
 . 
 FindDefaultCredentials 
 ( 
 ctx 
 ) 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 fmt 
 . 
 Errorf 
 ( 
 "failed to generate default credentials: %w" 
 , 
  
 err 
 ) 
  
 } 
  
 ts 
 , 
  
 err 
  
 := 
  
 idtoken 
 . 
 NewTokenSource 
 ( 
 ctx 
 , 
  
 url 
 , 
  
 option 
 . 
 WithCredentials 
 ( 
 credentials 
 )) 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 fmt 
 . 
 Errorf 
 ( 
 "failed to create NewTokenSource: %w" 
 , 
  
 err 
 ) 
  
 } 
  
 // Get the ID token. 
  
 // Once you've obtained the ID token, you can use it to make an authenticated call 
  
 // to the target audience. 
  
 _ 
 , 
  
 err 
  
 = 
  
 ts 
 . 
 Token 
 () 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 fmt 
 . 
 Errorf 
 ( 
 "failed to receive token: %w" 
 , 
  
 err 
 ) 
  
 } 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "Generated ID token.\n" 
 ) 
  
 return 
  
 nil 
 }

Node.js

To run this code sample, you must install the Google Auth Library for Node.js

  /** 
 * TODO(developer): 
 *  1. Uncomment and replace these variables before running the sample. 
 */ 
 // const targetAudience = 'http://www.example.com'; 
 const 
  
 { 
 GoogleAuth 
 } 
  
 = 
  
 require 
 ( 
 ' google-auth-library 
' 
 ); 
 async 
  
 function 
  
 getIdTokenFromMetadataServer 
 () 
  
 { 
  
 const 
  
 googleAuth 
  
 = 
  
 new 
  
  GoogleAuth 
 
 (); 
  
 const 
  
 client 
  
 = 
  
 await 
  
 googleAuth 
 . 
  getIdTokenClient 
 
 ( 
 targetAudience 
 ); 
  
 // Get the ID token. 
  
 // Once you've obtained the ID token, you can use it to make an authenticated call 
  
 // to the target audience. 
  
 await 
  
 client 
 . 
  idTokenProvider 
 
 . 
 fetchIdToken 
 ( 
 targetAudience 
 ); 
  
 console 
 . 
 log 
 ( 
 'Generated ID token.' 
 ); 
 } 
 getIdTokenFromMetadataServer 
 ();

Python

To run this code sample, you must install the Google Auth Python Library .

  import 
  
  google 
 
 import 
  
 google.oauth2.credentials 
 from 
  
 google.auth 
  
 import 
 compute_engine 
 import 
  
 google.auth.transport.requests 
 def 
  
 idtoken_from_metadata_server 
 ( 
 url 
 : 
 str 
 ): 
  
 """ 
 Use the Google Cloud metadata server in the Cloud Run (or AppEngine or Kubernetes etc.,) 
 environment to create an identity token and add it to the HTTP request as part of an 
 Authorization header. 
 Args: 
 url: The url or target audience to obtain the ID token for. 
 Examples: http://www.example.com 
 """ 
 request 
 = 
  google 
 
 . 
 auth 
 . 
 transport 
 . 
  requests 
 
 . 
  Request 
 
 () 
 # Set the target audience. 
 # Setting "use_metadata_identity_endpoint" to "True" will make the request use the default application 
 # credentials. Optionally, you can also specify a specific service account to use by mentioning 
 # the service_account_email. 
 credentials 
 = 
 compute_engine 
 . 
 IDTokenCredentials 
 ( 
 request 
 = 
 request 
 , 
 target_audience 
 = 
 url 
 , 
 use_metadata_identity_endpoint 
 = 
 True 
 ) 
 # Get the ID token. 
 # Once you've obtained the ID token, use it to make an authenticated call 
 # to the target audience. 
 credentials 
 . 
 refresh 
 ( 
 request 
 ) 
 # print(credentials.token) 
 print 
 ( 
 "Generated ID token." 
 )

Ruby

To run this code sample, you must install the Google Auth Library for Ruby .

  require 
  
 "googleauth" 
 ## 
 # Uses the Google Cloud metadata server environment to create an identity token 
 # and add it to the HTTP request as part of an Authorization header. 
 # 
 # @param url [String] The url or target audience to obtain the ID token for 
 #   (e.g. "http://www.example.com") 
 # 
 def 
  
 auth_cloud_idtoken_metadata_server 
  
 url 
 : 
  
 # Create the GCECredentials client. 
  
 id_client 
  
 = 
  
 Google 
 :: 
 Auth 
 :: 
  GCECredentials 
 
 . 
 new 
  
 target_audience 
 : 
  
 url 
  
 # Get the ID token. 
  
 # Once you've obtained the ID token, you can use it to make an authenticated call 
  
 # to the target audience. 
  
 id_client 
 . 
  fetch_access_token 
 
  
 puts 
  
 "Generated ID token." 
  
 id_client 
 . 
 refresh! 
 end

Use a connecting service to generate an ID token

Some Google Cloud services help you call other services. These connecting services might help determine when the call gets made, or manage a workflow that includes calling the service. The following services can automatically include an ID token, with the appropriate value for the aud claim, when they initiate a call to a service that requires an ID token:

Cloud Scheduler: Cloud Scheduler is a fully managed enterprise-grade cron job scheduler. You can configure Cloud Scheduler to include either an ID token or an access token when it invokes another service. For more information, see Using authentication with HTTP Targets .
Cloud Tasks: Cloud Tasks lets you manage the execution of distributed tasks. You can configure a task to include either an ID token or an access token when it calls a service. For more information, see Using HTTP Target tasks with authentication tokens .
Pub/Sub: Pub/Sub enables asynchronous communication between services. You can configure Pub/Sub to include an ID token with a message. For more information, see Authentication for push subscription .
Workflows: Workflows is a fully managed orchestration platform that executes services in an order that you define: a workflow . You can define a workflow to include either an ID token or an access token when it invokes another service. For more information, see Make authenticated requests from a workflow .

Generate an ID token by impersonating a service account

Service account impersonation allows a principal to generate short-lived credentials for a trusted service account. The principal can then use these credentials to authenticate as the service account.

Before a principal can impersonate a service account, it must have an IAM role on that service account that enables impersonation. If the principal is itself another service account, it might seem easier to simply provide the required permissions directly to that service account, and enable it to impersonate itself. This configuration, known as self-impersonation, creates a security vulnerability, because it lets the service account create an access token that can be refreshed in perpetuity.

Service account impersonation should always involve two principals: a principal that represents the caller, and the service account that is being impersonated, called the privilege-bearing service account.

To generate an ID token by impersonating a service account, you use the following general process.

For step-by-step instructions, see Create an ID token .

Identify or create a service account to be the privilege-bearing service account.
Identify the required roles to invoke the target service. Grant these roles to the service account on the target service:
- For Cloud Run services , grant the Cloud Run Invoker role ( roles/run.invoker ).
- For Cloud Run functions , grant the Cloud Functions Invoker role ( roles/cloudfunctions.invoker ).
- For other target services, see the product documentation for the service.
Identify the principal that will perform the impersonation, and set up Application Default Credentials (ADC) to use the credentials for this principal.

For development environments, the principal is usually the user account you provided to ADC by using the gcloud CLI. However, if you're running on a resource with a service account attached, the attached service account is the principal.
Grant the principal the Service Account OpenID Connect Identity Token Creator role ( roles/iam.serviceAccountOpenIdTokenCreator ).

Use the IAM Credentials API to generate the ID token for the authorized service account.

Replace the following:

AUDIENCE : The URI for the target service&mdashfor example, http://www.example.com .
SERVICE_ACCOUNT_EMAIL : The email address of the privilege-bearing service account.

 curl  
-X  
POST  
 \ 
-H  
 "Authorization: Bearer 
 $( 
gcloud  
auth  
print-access-token ) 
 " 
  
 \ 
-H  
 "Content-Type: application/json" 
  
 \ 
-d  
 '{"audience": " AUDIENCE 
", "includeEmail": "true"}' 
  
 \ 
https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/ SERVICE_ACCOUNT_EMAIL 
:generateIdToken

Generate a generic ID token for development with Cloud Run and Cloud Run functions

You can use the gcloud CLI to get an ID token for your user credentials that can be used with any Cloud Run service or Cloud Run function that the caller has the required IAM permissions to invoke. This token will not work for any other application.

To generate a generic ID token, you use the gcloud auth print-identity-token command :
```
 gcloud  
auth  
print-identity-token 
```

What's next

Understand ID tokens .
Use shell commands to query the Compute Engine metadata server .
Learn more about authentication methods .