oatk 0.2.0

A collection of useful functions for dealing with OAuth

oatk - OAuth Toolkit

A clean, simple Python OAuth toolkit for quick prototypes and learning. Provides both synchronous and asynchronous implementations with framework integrations for Flask, Quart, and FastAPI.

Quick Start

Installation

pip install oatk

For async support:

pip install oatk[async]

For framework integrations:

pip install oatk[quart]      # Quart (async Flask)
pip install oatk[fastapi]    # FastAPI

Basic Usage (Synchronous)

from oatk import OAuthToolkit

# Create and validate tokens
toolkit = OAuthToolkit()
toolkit.with_private("private_key.pem")
toolkit.with_public("public_key.pem")

# Create a token
toolkit.claims(user="alice", role="admin")
token = toolkit.token

# Validate a token
claims = toolkit.validate(token)
print(claims)  # {'user': 'alice', 'role': 'admin'}

Basic Usage (Asynchronous)

from oatk import AsyncOAuthToolkit

async def main():
    toolkit = AsyncOAuthToolkit()

    # Configure from OAuth provider
    await toolkit.using_provider(
        "https://accounts.google.com/.well-known/openid-configuration"
    )

    # Validate token
    claims = await toolkit.validate(token)
    print(claims)

# Or use with async context
async with AsyncOAuthToolkit() as toolkit:
    await toolkit.with_public("public_key.pem")
    claims = await toolkit.validate(token)

Flask Integration

from flask import Flask
from oatk import OAuthToolkit

app = Flask(__name__)
toolkit = OAuthToolkit()
toolkit.with_jwks("certs.json")

@app.route("/protected")
@toolkit.authenticated
def protected():
    return {"message": "authenticated"}

@app.route("/admin")
@toolkit.authenticated_with_claims(role="admin")
def admin():
    return {"message": "admin only"}

FastAPI Integration

from fastapi import FastAPI, Depends
from oatk.async_toolkit import AsyncOAuthToolkit
from oatk.fastapi import OAuthToolkitDependency

app = FastAPI()
toolkit = AsyncOAuthToolkit()
oauth = OAuthToolkitDependency(toolkit)

@app.get("/protected")
async def protected(user = Depends(oauth.get_current_user)):
    return {"user_id": user["sub"]}

@app.get("/admin")
async def admin(user = Depends(oauth.require_claims(role="admin"))):
    return {"message": "admin access"}

Features

Core Features

• Token creation with RSA private keys
• Token validation with RSA public keys
• JWKS import/export for key distribution
• Provider-based configuration (OpenID Connect)
• Token decoding (without validation)

Synchronous API (OAuthToolkit)

• Flask route decorators (@authenticated, @authenticated_with_claims)
• Command-line interface for quick operations
• Clipboard support (macOS)

Asynchronous API (AsyncOAuthToolkit)

• Async HTTP operations with httpx
• Async file I/O with anyio
• Framework-agnostic decorators
• Context-based token management

Framework Integrations

• Flask (sync): Route decorators for authentication
• Quart (async): Automatic token extraction from requests
• FastAPI (async): Dependency injection pattern

Command Line Interface

Generate a JWKS from a public key:

oatk with_public public_key.pem jwks

Create a token:

oatk with_private private_key.pem with_jwks certs.json claims '{"user":"alice"}' token

Validate a token:

oatk with_jwks certs.json from_file token.txt validate

Decode a token (without validation):

oatk from_file token.txt decode

Running Examples

The repository includes example applications demonstrating framework integrations. Use the Makefile targets to run them:

Quart Example (Async Flask)

make quart-example

This runs the Quart async OAuth example with auto-reload enabled. See examples/quart_example.py.

FastAPI Example

make fastapi-example

This runs the FastAPI async OAuth example with auto-reload enabled. See examples/fastapi_example.py.

Both examples demonstrate:

• OAuth toolkit initialization and configuration
• Token validation in route decorators
• Role-based access control
• Claim-based authorization

Documentation

Full documentation is available at: https://oatk.readthedocs.io

• Installation Guide
• Quick Start Tutorial
• Sync API Reference
• Async API Reference
• Framework Integrations
• API Reference

Use Cases

oatk is designed for:

• Quick prototypes: Get OAuth up and running in minutes
• Learning: Understand OAuth/JWT concepts with clean, readable code
• Development environments: Test OAuth flows without complex setup
• Understanding: See what's happening under the hood

For production systems, consider battle-tested alternatives like Authlib, python-jose, or similar.

Security Disclaimer

This software deals with authentication and authorization, which are critical security components. All software can contain bugs, including security vulnerabilities.

By using this software, you acknowledge that:

• You understand the security implications
• You take responsibility for any security-related issues
• This toolkit is designed primarily for prototypes and learning
• For production systems, consider battle-tested alternatives like Authlib, python-jose, or similar

USE AT YOUR OWN RISK. The authors and contributors are not responsible for any security breaches, data loss, or other damages resulting from the use of this software.

Requirements

• Python 3.9+
• RSA key pair (for token signing/validation)

Generate keys:

openssl genrsa -out private_key.pem 2048
openssl rsa -in private_key.pem -outform PEM -pubout -out public_key.pem

License

MIT License - see LICENSE.txt

Links

• PyPI
• GitHub
• Documentation
• Issue Tracker