scg-auth 1.0.0

A lightweight, zero-dependency OAuth 2.0 client library — Authorization Code, Client Credentials, Implicit, and Device Code flows with PKCE and CSRF protection

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, ...)

Parameter	Type	Required	Description
client_id	str	✓	OAuth client ID
authorization_url	str	✓	Provider authorization endpoint
token_url	str	✓	Provider token endpoint
client_secret	str		Client secret (required for confidential clients)
redirect_uri	str		Redirect URI
scopes	list[str]		Default scopes
device_authorization_url	str		Device authorization endpoint

Methods

Method	Description
generate_auth_url(pkce, state, scopes, response_type)	Build auth URL + register CSRF state
validate_state(state)	Validate CSRF state from callback
exchange_code(code, state, code_verifier)	Exchange code for tokens
client_credentials(scopes)	Client Credentials flow
refresh_token(refresh_token)	Refresh an access token
device_code(scopes)	Initiate Device Code flow
poll_device_token(response, timeout, interval)	Poll until user authorizes
generate_implicit_url(state, scopes)	Build Implicit flow auth URL
parse_implicit_response(url_or_fragment, validate_state)	Parse Implicit flow response
get_stored_tokens()	Get cached tokens
is_token_expired(buffer_seconds)	Check token expiry
clear_tokens()	Clear cached tokens

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