This page describes some ways to acquire a Google-signed OpenID Connect (OIDC) ID token.
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:
- 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
If you need an ID token to be accepted by an application not hosted on Trusted 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 Trusted 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 first complete the following steps:
- Install the Auth Client Library for Java
-
Set the
GOOGLE_CLOUD_UNIVERSE_DOMAIN
environment variable tos3nsapis.fr
.
Go
Before running code samples, set the GOOGLE_CLOUD_UNIVERSE_DOMAIN
environment
variable to s3nsapis.fr
.
Node.js
To run this code sample, you must first complete the following steps:
- Install the Google Auth Library for Node.js.
-
Set the
GOOGLE_CLOUD_UNIVERSE_DOMAIN
environment variable tos3nsapis.fr
.
Python
To run this code sample, you must first complete the following steps:
- Install the Google Auth Python Library.
-
Set the
GOOGLE_CLOUD_UNIVERSE_DOMAIN
environment variable tos3nsapis.fr
.
Ruby
To run this code sample, you must first complete the following steps:
- Install the Google Auth Library for Ruby.
-
Set the
GOOGLE_CLOUD_UNIVERSE_DOMAIN
environment variable tos3nsapis.fr
.
Use a connecting service to generate an ID token
Some Trusted 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.
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.
- Consult the product documentation to identify the required roles to invoke the target service. Grant these roles to the service account on the target 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
- AUDIENCE: The URI for the target service&mdashfor example,
What's next
- Understand ID tokens.
- Use shell commands to query the Compute Engine metadata server.
- Learn more about authentication methods.