oauth2fast-fastapi

🔐 Fast and secure OAuth2 authentication module for FastAPI with email verification and JWT tokens

📖 Conventions reference: this package follows the 2fast-handbook for ecosystem conventions (structure, versioning, README, commits, release).

Features

• 🔐 Complete OAuth2 Implementation: Full OAuth2 password flow with JWT tokens
• 📧 Email Verification: Built-in email verification system with customizable templates
• 👤 User Management: Ready-to-use user registration, login, and profile endpoints
• 🗄️ SQLModel Integration: Async PostgreSQL support with SQLModel/SQLAlchemy
• 🔑 Secure Password Hashing: Argon2 password hashing (winner of Password Hashing Competition)
• 🎯 FastAPI Dependencies: Easy-to-use dependencies for protected routes
• ⚡ Async/Await: Full async support for high performance
• 🎨 Customizable: Extend the User model with your own fields
• 📝 Type-Safe Configuration: Pydantic settings with environment variables
• 🔄 Email Templates: Jinja2 templates for verification and welcome emails

Installation

From PyPI (Recommended)

pip install oauth2fast-fastapi

From Source

# Clone the repository
git clone https://github.com/AngelDanielSanchezCastillo/oauth2fast-fastapi.git
cd oauth2fast-fastapi

# Install in development mode
pip install -e .

# Or install with dev dependencies
pip install -e ".[dev]"

Quick Start

1. Configure Environment Variables

Create a .env file in your project root:

# Required JWT Configuration
SECRET_KEY=your-super-secret-key-change-this-in-production
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=60

# Database Configuration
DB_DEFAULT_CONNECTION=auth
DB_CONNECTIONS__AUTH__HOST=localhost
DB_CONNECTIONS__AUTH__PORT=5432
DB_CONNECTIONS__AUTH__USERNAME=postgres
DB_CONNECTIONS__AUTH__PASSWORD=yourpassword
DB_CONNECTIONS__AUTH__DATABASE=myapp_db

# Mail Server Configuration
MAIL_DEFAULT_ACCOUNT=auth
MAIL_SMTP_ACCOUNTS__AUTH__HOST=smtp.gmail.com
MAIL_SMTP_ACCOUNTS__AUTH__PORT=587
MAIL_SMTP_ACCOUNTS__AUTH__USERNAME="noreply@yourapp.com"
MAIL_SMTP_ACCOUNTS__AUTH__PASSWORD="your-smtp-password"
MAIL_SMTP_ACCOUNTS__AUTH__SECURITY=tls
MAIL_SMTP_ACCOUNTS__AUTH__FROM_EMAIL="noreply@yourapp.com"
MAIL_SMTP_ACCOUNTS__AUTH__FROM_NAME="Your pp"
MAIL_SMTP_ACCOUNTS__AUTH__REPLY_TO="reply@yourapp.com"
MAIL_SMTP_ACCOUNTS__AUTH__TIMEOUT=60

# Application Settings
PROJECT_NAME=My App
FRONTEND_URL=https://yourapp.com
AUTH_URL_PREFIX=auth

2. Basic FastAPI Integration

from fastapi import FastAPI, Depends
from oauth2fast_fastapi import router, engine, get_current_user, User
from sqlmodel import SQLModel

app = FastAPI()

# Include authentication router
app.include_router(router, prefix="/auth", tags=["Authentication"])

@app.on_event("startup")
async def startup():
    # Create database tables
    async with engine.begin() as conn:
        await conn.run_sync(SQLModel.metadata.create_all)

@app.get("/profile")
async def get_profile(current_user: User = Depends(get_current_user)):
    return {
        "email": current_user.email,
        "name": f"{current_user.first_name} {current_user.last_name}",
        "verified": current_user.is_verified
    }

3. Authentication Flow

Register a new user:

POST /auth/users/register
{
  "email": "user@example.com",
  "password": "SecurePassword123",
  "first_name": "John",
  "last_name": "Doe"
}

Verify email:

POST /auth/users/verify-email
{
  "token": "verification-token-from-email"
}

Login:

POST /auth/token
Content-Type: application/x-www-form-urlencoded

username=user@example.com&password=SecurePassword123

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

Access protected endpoint:

GET /profile
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Protected Endpoints

Use the provided dependencies to protect your endpoints:

from fastapi import Depends
from oauth2fast_fastapi import get_current_user, get_current_verified_user, User

# Requires authentication only
@app.get("/dashboard")
async def dashboard(user: User = Depends(get_current_user)):
    return {"message": f"Welcome {user.email}"}

# Requires authentication AND email verification
@app.get("/premium")
async def premium_feature(user: User = Depends(get_current_verified_user)):
    return {"message": "Access granted to verified users only"}

Custom User Model

Extend the base User model with your own fields:

from oauth2fast_fastapi.models.user_model import User as BaseUser
from sqlmodel import Field

class CustomUser(BaseUser, table=True):
    __tablename__ = "custom_users"
    
    phone_number: str | None = Field(default=None)
    company: str | None = Field(default=None)
    role: str = Field(default="user")

Available Endpoints

The authentication router provides the following endpoints:

• POST /auth/users/register - Register a new user
• POST /auth/users/verify-email - Verify email with token
• POST /auth/users/resend-verification - Resend verification email
• POST /auth/token - Login and get JWT token
• GET /auth/users/me - Get current user profile
• PUT /auth/users/me - Update current user profile

Configuration Reference

All configuration is done via environment variables with nested delimiter __.

JWT Settings (Required)

• SECRET_KEY - Required: Secret key for JWT signing
• ALGORITHM - Default: "HS256": JWT algorithm
• ACCESS_TOKEN_EXPIRE_MINUTES - Default: 60: Token expiration time in minutes

Database Settings

• AUTH_DB__USERNAME - Database username
• AUTH_DB__PASSWORD - Database password
• AUTH_DB__HOSTNAME - Database host
• AUTH_DB__NAME - Database name
• AUTH_DB__PORT - Database port (default: 5432)

Mail Settings

• AUTH_MAIL_SERVER__USERNAME - SMTP username
• AUTH_MAIL_SERVER__PASSWORD - SMTP password
• AUTH_MAIL_SERVER__SERVER - SMTP server
• AUTH_MAIL_SERVER__PORT - SMTP port
• AUTH_MAIL_SERVER__FROM_DIRECTION - From email address
• AUTH_MAIL_SERVER__FROM_NAME - From name
• AUTH_MAIL_SERVER__STARTTLS - Use STARTTLS (default: false)
• AUTH_MAIL_SERVER__SSL_TLS - Use SSL/TLS (default: true)

Application Settings

• PROJECT_NAME - Application name (used in emails)
• FRONTEND_URL - Frontend URL (for email links)
• AUTH_URL_PREFIX - Auth router prefix (default: "auth")
• ENFORCE_EMAIL_VERIFICATION - Require email verification on /auth/token (default: false)
• VERIFICATION_GRACE_DAYS - Grace period in days for unverified users; unset = immediate rejection (default: none)

📚 Documentation

• Usage Guide - Comprehensive usage guide with examples
• Environment Configuration - All configuration options

📋 Naming Conventions

This package follows consistent naming conventions for models and database tables:

Model Classes (Python)

• Singular PascalCase
• Examples: User, Role, Permission, Tenant

Database Tables

• Plural snake_case
• Examples: users, roles, permissions, tenants

Many-to-Many Join Tables

• Plural snake_case on both table names
• Alphabetical order of the two table names
• Examples: role_users (r < u), permission_roles (p < r), tenant_users (t < u)

Mapping Tables (Multi-tenancy)

• In Auth DB: TenantUser class → tenant_users table (maps users ↔ tenants)
• In Tenant DB: User class → users table (local tenant user profile)

Generic Categories

• Use Category for generic categorization (not PermissionCategory)
• Can be reused across different entity types (roles, permissions, products, etc.)

📁 Module Structure

oauth2fast-fastapi/
├── pyproject.toml
├── MANIFEST.in
├── README.md
├── LICENSE
├── src/
│   └── oauth2fast_fastapi/
│       ├── __init__.py
│       ├── __version__.py
│       ├── settings.py          # Pydantic settings
│       ├── database.py          # Database engine
│       ├── dependencies.py      # FastAPI dependencies
│       ├── models/
│       │   ├── bases.py         # Base models
│       │   ├── mixins.py        # Model mixins
│       │   └── user_model.py    # User model
│       ├── routers/
│       │   ├── base_router.py   # Main router
│       │   └── users_router.py  # User endpoints
│       ├── schemas/
│       │   ├── token_schema.py  # JWT schemas
│       │   ├── user_schema.py   # User schemas
│       │   └── verification_schema.py
│       ├── utils/
│       │   ├── password_utils.py    # Password hashing
│       │   ├── token_utils.py       # JWT utilities
│       │   └── verification_utils.py
│       └── mail/
│           ├── connection.py    # SMTP connection
│           ├── service.py       # Email service
│           └── templates/       # Email templates
│               ├── verification.html
│               └── welcome.html
├── docs/
│   ├── env.example
│   └── usage.md
├── examples/
│   ├── basic_usage.py
│   ├── custom_user.py
│   └── complete_flow.py
└── tests/

Dependencies

This module depends on:

• FastAPI - Modern web framework (MIT License)
• Pydantic - Data validation (MIT License)
• SQLModel - SQL databases with Python (MIT License)
• SQLAlchemy - Database toolkit (MIT License)
• asyncpg - PostgreSQL driver (Apache 2.0)
• python-jose - JWT implementation (MIT License)
• passlib - Password hashing (BSD License)
• fastapi-mail - Email sending (MIT License)
• log2fast-fastapi - Logging module (MIT License)

We are grateful to the maintainers and contributors of these projects.

Security Features

• 🔒 Argon2 Password Hashing: Uses Argon2, the winner of the Password Hashing Competition
• 🎫 JWT Tokens: Secure token-based authentication
• ✉️ Email Verification: Prevents fake account creation
• 🔐 Secure Defaults: Sensible security defaults out of the box
• 🛡️ SQL Injection Protection: SQLModel/SQLAlchemy ORM prevents SQL injection

License

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

Copyright (c) 2026 Angel Daniel Sanchez Castillo

Note: This package is designed and maintained by the Solautyc Team for internal use. While publicly available under MIT license, use at your own risk.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and questions, please use the GitHub Issues page.