Google Auth

Warnings

• breaking cryptography is now a required (non-optional) dependency as of 2.48.0. The pure-Python rsa package was the previous fallback and has been fully removed in the 2.49.0-dev0 line. Environments that pin rsa or exclude cryptography will break on upgrade.
  Fix: Ensure cryptography is installed (it is now pulled in automatically). Remove any explicit rsa dependency pins. Do not install the legacy [rsa] extra expecting it to substitute for cryptography.
• breaking cachetools is no longer a dependency as of 2.47.0. Code that imported or type-annotated against cachetools classes for credential caching will break.
  Fix: Remove direct cachetools imports from google-auth credential caching logic. The library now uses its own lightweight internal cache.
• breaking The pyopenssl and enterprise_cert extras must never be installed together; they require conflicting versions of the cryptography package and will cause runtime errors.
  Fix: Choose one: pip install google-auth[pyopenssl] OR pip install google-auth[enterprise-cert], never both in the same environment.
• gotcha google.auth.default() returns a (credentials, project_id) tuple. project_id is None for user credentials (gcloud ADC) and may be None for some external account credentials. Silently passing None as a project to GCP client constructors causes subtle 400/403 errors.
  Fix: Always check: assert project is not None, or override with GOOGLE_CLOUD_PROJECT env var, or pass project explicitly to the client.
• gotcha Service account credentials returned by google.auth.default() via ADC are not automatically scoped. Calling google.auth.default() without passing scopes= yields credentials that may silently fail when making API calls requiring specific OAuth scopes.
  Fix: Always pass scopes=['https://www.googleapis.com/auth/cloud-platform'] (or specific scopes) to google.auth.default(). Alternatively call credentials.with_scopes([...]) on the returned object.
• deprecated oauth2client (GoogleCredentials.get_application_default()) is fully deprecated and unmaintained. It is not compatible with modern ADC features such as Workload Identity Federation and external account credentials.
  Fix: Migrate to google-auth: replace oauth2client imports with google.auth.default() or google.oauth2.service_account.Credentials.
• gotcha Python 3.7 support was dropped after 2.45.0, and Python 3.8/3.9 are end-of-life and will be dropped in a future release. Pinning google-auth on old Python runtimes may leave you unable to receive security fixes.
  Fix: Upgrade to Python 3.10+. If stuck on Python 3.7, pin google-auth<=2.45.0.

Install

• pip install google-auth Core (no transport)
• pip install google-auth[requests] With requests transport
• pip install google-auth[aiohttp] With async aiohttp transport

Imports

• google.auth.default

  import google.auth
  credentials, project = google.auth.default()

  oauth2client is deprecated; google-auth is its replacement. Never use oauth2client in new code.
• service_account.Credentials

  from google.oauth2 import service_account
  creds = service_account.Credentials.from_service_account_file('key.json')

  Service account credentials for server-to-server calls; must call .with_scopes() separately if scopes were not passed at construction time.
• google.auth.transport.requests.Request

  from google.auth.transport.requests import Request

  Used to build an HTTP Request object for refreshing credentials; requires the requests extra.
• google.oauth2.credentials.Credentials

  from google.oauth2.credentials import Credentials

  Holds OAuth 2.0 user credentials; typically produced by google-auth-oauthlib InstalledAppFlow, not constructed directly.
• google.auth.impersonated_credentials.Credentials

  from google.auth import impersonated_credentials

  Used to impersonate a service account; source credentials must have the Service Account Token Creator IAM role.
• google.auth.exceptions.DefaultCredentialsError

  from google.auth.exceptions import DefaultCredentialsError

  Raised by google.auth.default() when no credentials are found in the environment; always catch this, not a bare Exception.

Quickstart

Demonstrates Application Default Credentials (ADC) via google.auth.default() and explicit service account credentials. Set GOOGLE_APPLICATION_CREDENTIALS to a service account JSON key path, or authenticate locally with `gcloud auth application-default login`.

import os
import google.auth
from google.auth.transport.requests import Request
from google.oauth2 import service_account
from google.auth.exceptions import DefaultCredentialsError

# --- Option 1: Application Default Credentials (recommended for GCP-hosted workloads)
# Set GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json, or run:
#   gcloud auth application-default login
os.environ.setdefault('GOOGLE_APPLICATION_CREDENTIALS', os.environ.get('GOOGLE_APPLICATION_CREDENTIALS', ''))

try:
    credentials, project = google.auth.default(
        scopes=['https://www.googleapis.com/auth/cloud-platform']
    )
    # Force a token refresh so we can verify auth works
    credentials.refresh(Request())
    print(f'ADC OK — project={project}, token expiry={credentials.expiry}')
except DefaultCredentialsError as e:
    print(f'No credentials found: {e}')

# --- Option 2: Explicit service account key file
key_path = os.environ.get('GOOGLE_APPLICATION_CREDENTIALS', '')
if key_path:
    sa_creds = service_account.Credentials.from_service_account_file(
        key_path,
        scopes=['https://www.googleapis.com/auth/cloud-platform'],
    )
    sa_creds.refresh(Request())
    print(f'SA token expiry: {sa_creds.expiry}')