scg-auth (Python)

A lightweight, zero-dependency OAuth 2.0 client library for Python.

Supports all major OAuth 2.0 flows with built-in PKCE and CSRF protection. Uses the Python standard library only — no requests, no third-party packages.

Features

• Authorization Code Flow — with PKCE (S256) support
• Client Credentials Flow — machine-to-machine / service accounts
• Refresh Token — seamless token renewal
• Device Code Flow — CLI tools, smart TVs, IoT devices
• Implicit Flow — parse-only (deprecated in OAuth 2.1)
• State / CSRF protection — automatic state generation and validation
• Token management — in-memory storage with expiry checking
• Zero dependencies — standard library only (urllib, hashlib, secrets, etc.)

Installation

pip install scg-auth

Quick Start

Authorization Code Flow (with PKCE)

from scg_auth import SCGAuth

client = SCGAuth(
    client_id="your-client-id",
    client_secret="your-client-secret",
    authorization_url="https://provider.example.com/oauth/authorize",
    token_url="https://provider.example.com/oauth/token",
    redirect_uri="https://yourapp.com/callback",
    scopes=["openid", "profile", "email"],
)

# 1. Generate the authorization URL
result = client.generate_auth_url(pkce=True)
# Redirect user to result["url"], store result["state"] and result["code_verifier"]

# 2. Handle the callback
tokens = client.exchange_code(
    code,
    state=returned_state,      # validates CSRF automatically
    code_verifier=code_verifier,
)
print(tokens["access_token"])

# 3. Refresh when near expiry
if client.is_token_expired(buffer_seconds=120):
    tokens = client.refresh_token(tokens["refresh_token"])

Client Credentials Flow

tokens = client.client_credentials()
print(tokens["access_token"])

Device Code Flow

device_auth = client.device_code()
print(f"Visit {device_auth['verification_uri']} and enter: {device_auth['user_code']}")

tokens = client.poll_device_token(device_auth)
print(tokens["access_token"])

API

SCGAuth(client_id, authorization_url, token_url, ...)

Methods

Running Tests

cd python
python -m pytest test_scg_auth.py -v
# or
python test_scg_auth.py

License

MIT — Analytics With Harry / Squid Consultancy Group Limited