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

Cloud Run and Cloud Functions provide service-specific ways to get an ID token. For more information, see Authenticate to applications hosted on Cloud Run or Cloud 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 Google API Client Library for Java.

samples/snippets/src/main/java/IdTokenFromMetadataServer.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

auth/id_token_from_metadata_server.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

samples/idTokenFromMetadataServer.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.

samples/cloud-client/snippets/idtoken_from_metadata_server.py 

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.

samples/auth_cloud_idtoken_metadata_server.rb 
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:

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

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.

  1. Identify or create a service account to be the privilege-bearing service account. Grant that service account the required IAM role, on the target service:

    • For Cloud Run services, grant the Cloud Run Invoker role (roles/run.invoker).
    • For Cloud Functions, grant the Cloud Functions Invoker role (roles/cloudfunctions.invoker).
    • For other target services, see the product documentation for the service.

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

  3. Grant the principal the Service Account OpenID Connect Identity Token Creator role (roles/iam.serviceAccountOpenIdTokenCreator).

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

Generate a generic ID token for development with Cloud Run and Cloud 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 Function that the caller has the required IAM permissions to invoke. This token will not work for any other application.

Generate an ID token using an external identity provider

Generating an ID token using an external identity provider uses workload identity federation, which lets you set up a relationship between Google Cloud and your external identity provider. You can then use credentials supplied by your external identity provider to generate ID tokens or access tokens that can be used in Google Cloud.

To generate an ID token for credentials supplied from an external identity provider, follow these steps:

  1. Identify or create a service account to provide the IAM roles required to call the target service.

    It's a best practice to create a service account specifically for this purpose, and provide it with only the required role. This approach follows the principle of least privilege.

  2. 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 Functions, grant the Cloud Functions Invoker role (roles/cloudfunctions.invoker).
    • For other target services, see the product documentation for the service.

  3. Configure workload identity federation for your identity provider as described in Configuring workload identity federation.

  4. Follow the instructions in Granting external identities permission to impersonate a service account. Use the service account you set up in the previous steps as the service account to be impersonated.

  5. Use the REST API to acquire a short-lived token, but for the last step, use the generateIdToken method instead, to get an ID token:

    Bash

    ID_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": "AUDIENCE"
    }
EOF
)
echo $ID_TOKEN

    PowerShell

    $IdToken = (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" = "AUDIENCE"
    } | ConvertTo-Json)).token
Write-Host $IdToken

    Replace the following:

    • SERVICE_ACCOUNT_EMAIL: the email address of the service account
    • AUDIENCE: the audience for the token, such as the application or service that the token will be used to access

What's next