flask-advanced-auth

flask-advanced-auth is a production-grade, highly configurable JWT authentication extension for Flask and Flask-SQLAlchemy. It provides multi-rule support (different token lifetimes, secrets, and models for users vs. admins), built-in database token tracking, automatic token revocation (blacklisting), and clean route decorators.

✨ Features

• 🔑 Multi-Rule Authentication: Define distinct rules for different user tiers (e.g. users, managers, api_clients) with independent secrets, algorithms, and lifetimes.
• 🛡️ Easy Route Protection: Clean @authenticate(auth_classes=[AuthenticateJWT]) decorator with customizable 401 response and model injection into request.instance.
• 🔄 Access & Refresh Tokens: Native support for short-lived access tokens and long-lived refresh tokens with convenient refresh_access_token() helper.
• 🚫 Token Revocation (Blacklisting): Built-in revocation mechanism with database persistence and logout() helper.
• 📊 Token Tracking: Track issued tokens in the database to detect anomalies, enforce single-session limits, or audit activity.
• 🔌 Multiple Extraction Strategies: Extract tokens from Authorization: Bearer <token> headers, HTTP cookies, or URL query parameters.
• ⚡ Pydantic Validation: Strict configuration schema validation powered by Pydantic V2 with flexible aliases.
• 🧪 Thoroughly Tested: 100% test pass rate with ≥ 88% test coverage.

📦 Installation

pip install flask-advanced-auth

Or install with development dependencies:

pip install flask-advanced-auth[dev]

🚀 Quick Start (5 Minutes)

1. Configure Rules & Bootstrap

from datetime import timedelta
from flask import Flask, jsonify, request
from flask_sqlalchemy import SQLAlchemy
from flask_advanced_auth import (
    initialize_jwt_authentication,
    authenticate,
    AuthenticateJWT,
    TokenFactory,
    refresh_access_token,
    logout,
)

app = Flask(__name__)
app.config["SECRET_KEY"] = "your-app-secret"
app.config["SQLALCHEMY_DATABASE_URI"] = "sqlite:///app.db"
db = SQLAlchemy(app)

# Define your JWT rules
JWT_RULES = {
    "default": {
        "description": "Standard user access token",
        "secret_key": "your-jwt-secret-key",
        "algorithm": "HS256",
        "access_token_lifetime": timedelta(minutes=15),
        "refresh_token_lifetime": timedelta(days=7),
        "token_header": "Bearer ",
    }
}

# Initialize flask-advanced-auth
initialize_jwt_authentication(
    database_path="app.db",
    rules=JWT_RULES,
)

2. Issue Tokens on Login

@app.route("/api/login", methods=["POST"])
def login():
    username = request.json.get("username")
    
    factory = TokenFactory()
    access_token = factory.generate_token(
        rule_name="default",
        extra_payload={"sub": username},
    )
    refresh_token = factory.generate_refresh_token(
        rule_name="default",
        extra_payload={"sub": username},
    )
    
    return jsonify({
        "access_token": access_token,
        "refresh_token": refresh_token,
    })

3. Protect Routes

@app.route("/api/dashboard")
@authenticate(auth_classes=[AuthenticateJWT], rule_name="default")
def dashboard():
    return jsonify({"message": "Welcome to your protected dashboard!"})

4. Refresh Tokens & Logout

@app.route("/api/refresh", methods=["POST"])
def refresh():
    token = request.json.get("refresh_token")
    new_access_token = refresh_access_token(token, rule_name="default")
    return jsonify({"access_token": new_access_token})

@app.route("/api/logout", methods=["POST"])
def user_logout():
    token = request.headers.get("Authorization", "").replace("Bearer ", "")
    logout(token, rule_name="default")
    return jsonify({"message": "Token revoked successfully."})

⚙️ Configuration Reference

Rules are passed as a dictionary where each key represents a rule name (e.g. "default", "admin"):

🧩 Authentication Strategies

You can choose how tokens are extracted by passing different authentication classes to @authenticate:

from flask_advanced_auth import (
    authenticate,
    HeaderAuthentication,   # Reads Authorization: Bearer <token>
    CookieAuthentication,   # Reads token from HTTP cookies
    QueryParamAuthentication, # Reads ?token=<token>
)

# 1. From Authorization header
@app.route("/api/v1/data")
@authenticate(auth_classes=[HeaderAuthentication])
def api_data():
    return {"status": "ok"}

# 2. From Cookie
@app.route("/web/profile")
@authenticate(auth_classes=[CookieAuthentication])
def web_profile():
    return {"status": "ok"}

# 3. From URL parameter (e.g., SSE or WebSocket connection handshake)
@app.route("/stream")
@authenticate(auth_classes=[QueryParamAuthentication])
def stream():
    return {"status": "connected"}

🗄️ Database Model Mixins

When enabling track_created or blacklisted, use our ready-to-use SQLAlchemy model mixins:

from flask_advanced_auth.models import AbstractTrackModelMixin, AbstractBlackListModelMixin
from myapp.database import db

class TrackedToken(db.Model, AbstractTrackModelMixin):
    __tablename__ = "tracked_tokens"

class BlacklistedToken(db.Model, AbstractBlackListModelMixin):
    __tablename__ = "blacklisted_tokens"

🧪 Running Tests

# Run tests with coverage
pytest -v

# Run single test module
pytest tests/test_decorators.py -v

🤝 Contributing

Contributions are welcome! Please check out CONTRIBUTING.md for setup instructions and guidelines.

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.