google.oauth2.id_token module

Google ID Token helpers.

Provides support for verifying OpenID Connect ID Tokens, especially ones generated by Google infrastructure.

To parse and verify an ID Token issued by Google’s OAuth 2.0 authorization server use verify_oauth2_token(). To verify an ID Token issued by Firebase, use verify_firebase_token().

A general purpose ID Token verifier is available as verify_token().

Example:

from google.oauth2 import id_token
from google.auth.transport import requests

request = requests.Request()

id_info = id_token.verify_oauth2_token(
    token, request, 'my-client-id.example.com')

userid = id_info['sub']

By default, this will re-fetch certificates for each verification. Because Google’s public keys are only changed infrequently (on the order of once per day), you may wish to take advantage of caching to reduce latency and the potential for network errors. This can be accomplished using an external library like CacheControl to create a cache-aware google.auth.transport.Request:

import cachecontrol
import google.auth.transport.requests
import requests

session = requests.session()
cached_session = cachecontrol.CacheControl(session)
request = google.auth.transport.requests.Request(session=cached_session)
verify_token(id_token, request, audience=None, certs_url='https://www.googleapis.com/oauth2/v1/certs', clock_skew_in_seconds=0)[source]

Verifies an ID token and returns the decoded token.

Parameters:

  • id_token (Union [ str, bytes ]) – The encoded token.

  • request (google.auth.transport.Request) – The object used to make HTTP requests.

  • audience (str or list) – The audience or audiences that this token is intended for. If None then the audience is not verified.

  • certs_url (str) – The URL that specifies the certificates to use to verify the token. This URL should return JSON in the format of {'key id': 'x509 certificate'}.

  • clock_skew_in_seconds (int) – The clock skew used for iat and exp validation.

Returns:

The decoded token.

Return type:

Mapping [ str, Any ]

verify_oauth2_token(id_token, request, audience=None, clock_skew_in_seconds=0)[source]

Verifies an ID Token issued by Google’s OAuth 2.0 authorization server.

Parameters:

  • id_token (Union [ str, bytes ]) – The encoded token.

  • request (google.auth.transport.Request) – The object used to make HTTP requests.

  • audience (str) – The audience that this token is intended for. This is typically your application’s OAuth 2.0 client ID. If None then the audience is not verified.

  • clock_skew_in_seconds (int) – The clock skew used for iat and exp validation.

Returns:

The decoded token.

Return type:

Mapping [ str, Any ]

Raises:
verify_firebase_token(id_token, request, audience=None, clock_skew_in_seconds=0)[source]

Verifies an ID Token issued by Firebase Authentication.

Parameters:

  • id_token (Union [ str, bytes ]) – The encoded token.

  • request (google.auth.transport.Request) – The object used to make HTTP requests.

  • audience (str) – The audience that this token is intended for. This is typically your Firebase application ID. If None then the audience is not verified.

  • clock_skew_in_seconds (int) – The clock skew used for iat and exp validation.

Returns:

The decoded token.

Return type:

Mapping [ str, Any ]

fetch_id_token_credentials(audience, request=None)[source]

Create the ID Token credentials from the current environment.

This function acquires ID token from the environment in the following order. See https://google.aip.dev/auth/4110.

  1. If the environment variable GOOGLE_APPLICATION_CREDENTIALS is set to the path of a valid service account JSON file, then ID token is acquired using this service account credentials.

  2. If the application is running in Compute Engine, App Engine or Cloud Run, then the ID token are obtained from the metadata server.

  3. If metadata server doesn’t exist and no valid service account credentials are found, DefaultCredentialsError will be raised.

Example:

import google.oauth2.id_token
import google.auth.transport.requests

request = google.auth.transport.requests.Request()
target_audience = "https://pubsub.googleapis.com"

# Create ID token credentials.
credentials = google.oauth2.id_token.fetch_id_token_credentials(target_audience, request=request)

# Refresh the credential to obtain an ID token.
credentials.refresh(request)

id_token = credentials.token
id_token_expiry = credentials.expiry
Parameters:

  • audience (str) – The audience that this ID token is intended for.

  • request (Optional [ google.auth.transport.Request ]) – A callable used to make HTTP requests. A request object will be created if not provided.

Returns:

The ID token credentials.

Return type:

google.auth.credentials.Credentials

Raises:

DefaultCredentialsError – If metadata server doesn’t exist and no valid service account credentials are found.

fetch_id_token(request, audience)[source]

Fetch the ID Token from the current environment.

This function acquires ID token from the environment in the following order. See https://google.aip.dev/auth/4110.

  1. If the environment variable GOOGLE_APPLICATION_CREDENTIALS is set to the path of a valid service account JSON file, then ID token is acquired using this service account credentials.

  2. If the application is running in Compute Engine, App Engine or Cloud Run, then the ID token are obtained from the metadata server.

  3. If metadata server doesn’t exist and no valid service account credentials are found, DefaultCredentialsError will be raised.

Example:

import google.oauth2.id_token
import google.auth.transport.requests

request = google.auth.transport.requests.Request()
target_audience = "https://pubsub.googleapis.com"

id_token = google.oauth2.id_token.fetch_id_token(request, target_audience)
Parameters:
Returns:

The ID token.

Return type:

str

Raises:

DefaultCredentialsError – If metadata server doesn’t exist and no valid service account credentials are found.