This AIP is currently a draft. This means that it is being actively debated and discussed, and it may change in non-trivial ways.

AIP-4116

Identity Tokens

Identity Tokens (or ID Tokens) are JSON Web Tokens (JWT) with additional claims pertaining to the identity of the client or end-user (such as "email"). Which additional claims fields are included in the ID token are dependent on the ID token provider.

The fetching of ID tokens is used to:

• request a protected Cloud Run service, which requires a valid ID token in the Authentication header.
• request an IAP-protected resource, which requires a valid ID token in the Authentication header.

The validation of ID tokens should be done by:

• services receiving an authenticated PubSub push message sent outside of Google Cloud.

Note: Because this AIP describes guidance and requirements in a language-neutral way, it uses generic terminology which may be imprecise or inappropriate in certain languages or environments.

Guidance

This section describes the general guidance of ID tokens as a means of authentication.

ID tokens obtained by Application Default Credentials

When a target audience is provided by the developer, ADC should fetch an ID token with the credentials provided. For example, if service account keys are provided, ADC will request an ID token from the OAuth token endpoint. If virtual machine credentials are provided, ADC will request an ID token from the virtual machine server.

Expected Behavior for Fetching ID Tokens

To support fetching ID Tokens, the auth libraries must follow the steps below:

1. Accept a target audience parameter when Application Default Credentials are requested. If a target audience and scope are both provided to the auth library, an exception must be thrown.

2. Virtual machine credentials return the ID token retrieved from the metadata server's instance/service-accounts/default/identity endpoint, setting the audience querystring parameter to the provided target audience.

3. Service account Keys use the JWT Bearer grant type, and set the target_audience claim to the provided target audience. This will return a JSON object containing an id_token key.

User Identity flows may be used to issue ID tokens, but are not required to.

Expected Behavior for Verifying ID Tokens

To support verifying ID Tokens, the auth libraries must provide a method to validate a JWT token which can do the following:

1. Validate a JWT with an ES256 signature. 2. Validate JWT aud claim against a user-provided audience. 3. Validate JWT exp claim against the current timestamp.