Get an ID token

Stay organized with collections Save and categorize content based on your preferences.

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:

Cloud Build includes a metadata server, but it does not return ID tokens.

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.


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.");
  }
}

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.abc.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.")

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.
Tasks
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, follow these steps:

  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 required roles to impersonate the privilege-bearing service account.

    For step-by-step instructions, see Provide required permissions in the IAM documentation.

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

    For step-by-step instructions, see Generating OpenID Connect ID tokens.

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