Authlib: OAuth & OpenID Connect Library

Warnings

• gotcha When developing locally without HTTPS, Authlib will raise an `InsecureTransportError` as OAuth 2.0 strictly requires HTTPS. To bypass this for local testing, set the environment variable `AUTHLIB_INSECURE_TRANSPORT` to `1` or `true`. This should NEVER be used in production.
  Fix: Set `os.environ['AUTHLIB_INSECURE_TRANSPORT'] = '1'` in your development environment, or ensure your application is served over HTTPS.
• breaking Authlib v1.0.0 introduced significant breaking changes, including dropping Python 2 support, removing built-in SQLAlchemy integration, and restructuring framework integrations. If using Flask OAuth 2.0 provider, `OAUTH2_JWT_XXX` configurations were removed, requiring developers to define `.get_jwt_config` on OpenID extensions and grant types.
  Fix: Upgrade to Python 3.9+ and refactor client/server integrations according to the new `authlib.integrations` structure. For OAuth 2.0 providers, adapt JWT configuration methods.
• breaking In Authlib v1.1.0, the default `authlib.jose.jwt` instance was restricted to only work with JSON Web Signature (JWS) algorithms. If you need to use JWT with JSON Web Encryption (JWE) algorithms, you must explicitly pass the `algorithms` parameter to `JsonWebToken`.
  Fix: For JWE, instantiate `JsonWebToken` with allowed algorithms: `from authlib.jose import JsonWebToken; jwt_instance = JsonWebToken(['A128KW', 'A128GCM', 'DEF'])`.
• gotcha By default, `authlib.jose.jwt.decode` parses the `alg` header, potentially allowing symmetric MACs (e.g., HS256) and asymmetric signatures (e.g., RS256) to be combined. This can lead to a signature bypass (CVE-2016-10555).
  Fix: Explicitly restrict allowed algorithms when decoding by instantiating `JsonWebToken` with a list of trusted algorithms, or use a custom key loader that provides different keys for symmetric and asymmetric signatures.
• deprecated The `authlib.jose` module is being split into a separate `joserfc` package. While still part of Authlib v1.x, this indicates a future architectural shift that may lead to breaking changes in `jose` imports or functionality in Authlib v2.x.
  Fix: Keep an eye on future Authlib major releases for official migration guides. For now, be aware that direct `jose` imports might change or require installing `joserfc` separately in the future.

Install

• pip install Authlib Base Installation
• pip install Authlib requests # For Requests-based OAuth clients Requests Integration
• pip install Authlib httpx # For HTTPX-based async OAuth clients HTTPX Integration (Async)
• pip install Authlib Flask # For Flask integrations Flask Integration

Imports

• OAuth

  from authlib.integrations.flask_client import OAuth

  For integrating OAuth clients with Flask applications. Similar imports exist for Django, Starlette, and FastAPI.
• OAuth2Session

  from authlib.integrations.requests_client import OAuth2Session

  Client-related classes were moved under `authlib.integrations` in v0.13+. Direct use of `OAuthClient` is for framework integrations, use `OAuth2Session` for making individual requests.
• jwt

  from authlib.jose import jwt

  For JWT encoding/decoding. The `jose` module is planned to be split into a separate `joserfc` package in future major versions. Consider using `JsonWebToken` for explicit algorithm control.
• AuthorizationServer

  from authlib.integrations.flask_oauth2 import AuthorizationServer

  For building an OAuth 2.0 authorization server with Flask.

Quickstart

This Flask example demonstrates how to set up an OAuth 2.0 client using Authlib for 'Login with Google'. It registers Google as an OAuth provider, redirects users for authorization, and handles the callback to exchange the authorization code for tokens and retrieve user information. It includes configuration for environment variables and addresses the `InsecureTransportError` for local development.

import os
from flask import Flask, redirect, url_for, session, jsonify
from authlib.integrations.flask_client import OAuth

app = Flask(__name__)
app.secret_key = os.environ.get('FLASK_SECRET_KEY', 'super-secret-key')
app.config['GOOGLE_CLIENT_ID'] = os.environ.get('GOOGLE_CLIENT_ID', '')
app.config['GOOGLE_CLIENT_SECRET'] = os.environ.get('GOOGLE_CLIENT_SECRET', '')
app.config['GOOGLE_AUTHORIZE_URL'] = 'https://accounts.google.com/o/oauth2/auth'
app.config['GOOGLE_ACCESS_TOKEN_URL'] = 'https://oauth2.googleapis.com/token'
app.config['GOOGLE_USERINFO_ENDPOINT'] = 'https://openidconnect.googleapis.com/v1/userinfo'
app.config['GOOGLE_JWKS_URI'] = 'https://www.googleapis.com/oauth2/v3/certs'

# Configure a dummy URL for local testing
# In a real app, ensure this is HTTPS and a valid redirect URI configured with your OAuth provider
app.config['GOOGLE_REDIRECT_URI'] = os.environ.get('GOOGLE_REDIRECT_URI', 'http://127.0.0.1:5000/authorize')

oauth = OAuth(app)

oauth.register(
    'google',
    client_id=app.config['GOOGLE_CLIENT_ID'],
    client_secret=app.config['GOOGLE_CLIENT_SECRET'],
    authorize_url=app.config['GOOGLE_AUTHORIZE_URL'],
    access_token_url=app.config['GOOGLE_ACCESS_TOKEN_URL'],
    userinfo_endpoint=app.config['GOOGLE_USERINFO_ENDPOINT'],
    jwks_uri=app.config['GOOGLE_JWKS_URI'], # Required for OIDC id_token validation
    client_kwargs={'scope': 'openid email profile'}
)

@app.route('/')
def index():
    user = session.get('user')
    if user:
        return f'Hello, {user.get("name", "User")}! <a href="/logout">Logout</a>'
    return '<a href="/login">Login with Google</a>'

@app.route('/login')
def login():
    redirect_uri = url_for('authorize', _external=True)
    return oauth.google.authorize_redirect(redirect_uri)

@app.route('/authorize')
def authorize():
    try:
        token = oauth.google.authorize_access_token()
        userinfo = oauth.google.parse_id_token(token)
        session['user'] = userinfo
        return redirect('/')
    except Exception as e:
        return f'Authorization failed: {e}', 400

@app.route('/logout')
def logout():
    session.pop('user', None)
    return redirect('/')

if __name__ == '__main__':
    # For local development, allow insecure transport
    # NEVER use in production without proper HTTPS setup
    os.environ['AUTHLIB_INSECURE_TRANSPORT'] = '1'
    print("To run, set environment variables like:")
    print("export FLASK_SECRET_KEY='your-flask-secret-key'")
    print("export GOOGLE_CLIENT_ID='YOUR_GOOGLE_CLIENT_ID'")
    print("export GOOGLE_CLIENT_SECRET='YOUR_GOOGLE_CLIENT_SECRET'")
    print("Then: flask --app YOUR_APP_FILE.py run")
    app.run(debug=True)