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')

if id_info['iss'] != 'https://accounts.google.com':
    raise ValueError('Wrong issuer.')

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')[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) – The audience 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'}.

Returns

The decoded token.

Return type

Mapping [ str, Any ]

verify_oauth2_token(id_token, request, audience=None)[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.

Returns

The decoded token.

Return type

Mapping [ str, Any ]

verify_firebase_token(id_token, request, audience=None)[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.

Returns

The decoded token.

Return type

Mapping [ str, Any ]

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:

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

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

  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.