the37lab-authlib 0.1.1751369506

Python SDK for the Authlib

AuthLib

A Python authentication library that provides JWT, OAuth2, and API token authentication with PostgreSQL backend. This library is designed for seamless integration with Flask applications and provides a robust set of endpoints and utilities for user management, authentication, and API token handling.

Table of Contents

• AuthLib
  • Table of Contents
  • Installation
  • Quick Start
  • Configuration
    • Required Parameters
    • Optional Parameters
      • Example oauth_config:
  • API Endpoints
    • Authentication
    • User Management
    • API Tokens
  • Authentication Flow
  • User Object
  • Token Management
  • Development
    • Setup
    • Database Setup
    • Running Tests
  • API Token Override for Testing
    • Usage
    • Warning

Installation

pip install -e .

Quick Start

from flask import Flask
from authlib import AuthManager

app = Flask(__name__)

# Option 1: Explicit configuration
auth = AuthManager(
    app=app,
    db_dsn="postgresql://user:pass@localhost/dbname",
    jwt_secret="your-secret-key",
    oauth_config={
        "google": {
            "client_id": "your-client-id",
            "client_secret": "your-client-secret"
        }
    }
)

# Option 2: Use environment variables with a prefix (e.g., AMPA_)
# This will load:
#   AMPA_DATABASE_URL, AMPA_JWT_SECRET, AMPA_GOOGLE_CLIENT_ID, AMPA_GOOGLE_CLIENT_SECRET
# auth = AuthManager(app=app, environment_prefix="AMPA")

@app.route("/protected")
@auth.require_auth(roles=["admin"])
def protected_route():
    return "Protected content"

@app.route("/public")
@auth.public_endpoint
def custom_public_route():
    return "Public content"

AuthManager's blueprint now registers a global error handler for AuthError and authenticates requests for all of its routes by default. Authenticated users are made available as flask.g.requesting_user. Only the login, OAuth, token refresh, registration and role listing endpoints are exempt from this check. Additional routes can be marked as public using the @auth.public_endpoint decorator or auth.add_public_endpoint("auth.some_endpoint").

Configuration

Required Parameters

• app: Flask application instance
• db_dsn: PostgreSQL connection string
• jwt_secret: Secret key for JWT signing

Optional Parameters

• oauth_config: Dictionary of OAuth provider configurations (see below)
• token_expiry: JWT token expiry time in seconds (default: 3600)
• refresh_token_expiry: Refresh token expiry time in seconds (default: 2592000)
• environment_prefix: If set, loads all configuration from environment variables with this prefix (e.g., AMPA_DATABASE_URL, AMPA_JWT_SECRET, AMPA_GOOGLE_CLIENT_ID, AMPA_GOOGLE_CLIENT_SECRET). Overrides other config if set.

Example oauth_config:

{
    "google": {
        "client_id": "...",
        "client_secret": "..."
    },
    "github": {
        "client_id": "...",
        "client_secret": "..."
    }
}

API Endpoints

Authentication

• POST /api/v1/users/login - Login with username/password
  • Request: { "username": "string", "password": "string" }
  • Response: { "token": "jwt", "refresh_token": "jwt", "user": { ... } }
• POST /api/v1/users/login/oauth - Get OAuth redirect URL
  • Request: { "provider": "google|github|..." }
  • Response: { "redirect_url": "string" }
• GET /api/v1/users/login/oauth2callback - OAuth callback
  • Query Params: code, state, provider
  • Response: { "token": "jwt", "refresh_token": "jwt", "user": { ... } }
• POST /api/v1/users/token-refresh - Refresh JWT token
  • Request: { "refresh_token": "jwt" }
  • Response: { "token": "jwt", "refresh_token": "jwt" }

User Management

• POST /api/v1/users/register - Register new user
  • Request: { "username": "string", "password": "string", "email": "string", ... }
  • Response: { "user": { ... }, "token": "jwt", "refresh_token": "jwt" }
• GET /api/v1/users/login/profile - Get user profile
  • Auth: Bearer JWT
  • Response: { "user": { ... } }
• GET /api/v1/users/roles - Get available roles
  • Response: [ "admin", "user", ... ]

API Tokens

• POST /api/v1/users/{user}/api-tokens - Create API token
  • Request: { "name": "string", "scopes": [ ... ] }
  • Response: { "token": "string", "id": "uuid", ... }
• GET /api/v1/users/{user}/api-tokens - List API tokens
  • Response: [ { "id": "uuid", "name": "string", ... } ]
• DELETE /api/v1/users/{user}/api-tokens/{token_id} - Delete API token
  • Response: { "success": true }

Authentication Flow

1. Login:
   • User submits credentials to /api/v1/users/login.
   • Receives JWT and refresh token.
2. Token Refresh:
   • Use /api/v1/users/token-refresh with refresh token to get new JWT.
3. OAuth:
   • Get redirect URL from /api/v1/users/login/oauth.
   • Complete OAuth flow via /api/v1/users/login/oauth2callback.
4. Protected Routes:
   • All routes inside the provided blueprint are authenticated by default. The authenticated user can be accessed via g.requesting_user. Use @auth.require_auth() to protect custom routes in your application.

User Object

The user object returned by the API typically includes:

{
  "id": "uuid",
  "username": "string",
  "email": "string",
  "roles": ["user", "admin"],
  "created_at": "timestamp",
  "last_login": "timestamp"
}

Token Management

• JWT: Used for authenticating API requests. Include in Authorization: Bearer <token> header.
• Refresh Token: Used to obtain new JWTs without re-authenticating.
• API Tokens: Long-lived tokens for programmatic access, managed per user.

Development

Setup

1. Clone the repository
2. Create virtual environment:

python -m venv venv
venv\Scripts\activate

3. Install dependencies:

pip install -e ".[dev]"

Database Setup

createdb authlib
python -m authlib.cli db init

Running Tests

pytest

API Token Override for Testing

For testing purposes, you can bypass the database and provide a static mapping of API tokens to usernames using the api_tokens argument to AuthManager or the {PREFIX}API_TOKENS environment variable.

Usage

• Constructor argument:

  AuthManager(api_tokens={"token1": "user1", "token2": "user2"})
  

• Environment variable: Set {PREFIX}API_TOKENS to a comma-separated list of token:username pairs, e.g.:

  export MYAPP_API_TOKENS="token1:user1,token2:user2"
  

  Replace MYAPP with your environment prefix.

Warning: This method is intended only for testing and development. Do not use this approach in production environments.