oauth2client

oauth2client is Google’s original Python library for handling OAuth 2.0 authentication and authorization flows against Google APIs. It provides credential classes for web server flows, installed applications, service accounts, and Google App Engine, along with pluggable storage backends for persisting tokens across processes and restarts.

The library predates Google’s current authentication stack and has been officially deprecated since 2017. Google recommends new projects use google-auth combined with oauthlib instead, but oauth2client remains present in a long tail of older Python codebases, tutorials, and pinned dependency trees that integrate with Google Cloud, Google Workspace, and other Google APIs.

What You Get

• OAuth2WebServerFlow - drives the standard three-legged OAuth 2.0 web server flow used by most Google API integrations
• ServiceAccountCredentials - authenticates as a Google Cloud service account using a JWT-signed assertion, no user interaction required
• Storage backends - pluggable persistence for credentials via file.Storage, plus contrib modules for SQLAlchemy, Django, Flask, keyring, and multiprocess file locking
• App Engine integration - contrib/appengine.py wires credentials into GAE’s NDB datastore and decorators for request handlers
• Device flow support - DeviceFlowInfo and related helpers implement the OAuth 2.0 device authorization grant for input-constrained devices
• Crypto abstraction - crypt.py and the _pycrypto_crypt/_openssl_crypt/_pure_python_crypt modules select an available backend for signing and verifying JWTs

Common Use Cases

• Legacy Google API scripts - older Python tools that call Google Sheets, Drive, or Cloud APIs and were written before google-auth existed
• Service account automation - server-to-server jobs that authenticate as a Google Cloud service account without a browser-based consent screen
• App Engine applications - GAE apps built on the legacy standard environment that use the contrib.appengine decorators for per-user OAuth
• Maintaining pinned dependencies - teams stuck on oauth2client because a transitive dependency (e.g. an older gspread or google-api-python-client release) still requires it

Under The Hood

Architecture The library is organized around a small class hierarchy rooted in client.Credentials, with OAuth2Credentials as the workhorse that tracks access/refresh tokens and re-authorizes HTTP requests via authorize(). Specialized subclasses (GoogleCredentials, AssertionCredentials, ServiceAccountCredentials in service_account.py) layer on top for application-default discovery and JWT-signed service account flows, while Flow/OAuth2WebServerFlow model the interactive three-legged grant and Storage (implemented per-backend under contrib/, plus file.Storage) abstracts persistence. This separation means swapping how credentials are stored (file, SQLAlchemy, keyring, App Engine datastore) requires only a new Storage subclass, not changes to the credential or flow classes; changing the core OAuth2Credentials token-refresh logic, however, would ripple through every subclass and contrib integration.

Tech Stack Built for Python 2.7 and 3.4+, the library depends on httplib2 for HTTP transport, six for py2/3 compatibility shims, and pyasn1/pyasn1-modules/rsa for certificate and signature handling. Cryptographic operations are abstracted across three interchangeable backends (_pycrypto_crypt.py, _openssl_crypt.py, _pure_python_crypt.py) selected at import time based on what’s installed, with PyOpenSSL and PyCrypto as optional extras declared in setup.py. The contrib/ package adds optional integrations for Flask, Django, SQLAlchemy, GCE metadata, and App Engine’s NDB, each importable independently so the core library has no hard dependency on any web framework.

Code Quality Tests live under tests/, mirror the module layout (test_client.py, test_crypt.py, test_service_account.py, etc.), and use the standard unittest framework with mock for HTTP and crypto stubbing, run via tox.ini across multiple Python versions and CI configured in .travis.yml. Error handling is explicit and typed, with a dedicated exception hierarchy (Error, FlowExchangeError, AccessTokenRefreshError, CryptoUnavailableError, etc.) rather than bare exceptions. There is no static type-checking or linter configuration in the repo, and the project has been functionally frozen since its 2017 deprecation — the last commit predates modern Python packaging and typing conventions.

API Design The public surface favors explicit credential construction and refresh over convenience, requiring callers to instantiate the right credential class for their flow (web server, installed app, service account, or GCE) rather than a single unified entry point — GoogleCredentials.get_application_default() is the closest thing to an ergonomic default. Documentation is comprehensive for its era (readthedocs-hosted docs, docstrings throughout client.py), but the API predates conveniences like async support or context managers, and the deprecation notice itself is now the most prominent piece of guidance a new user encounters.