413 lines
14 KiB
Markdown
413 lines
14 KiB
Markdown
# MyAuth Module
|
|
|
|
A reusable, modular authentication system for FastAPI applications, designed for deployment on an internal PyPI server.
|
|
|
|
## Overview
|
|
|
|
MyAuth provides a complete, 'out-of-the-box' authentication solution for your FastAPI projects. It's designed to be
|
|
installed as a dependency and configured in just a few lines, letting you focus on your business logic instead of user
|
|
and token management.
|
|
|
|
This module handles registration, login/logout, email verification, password reset, and token management (JWT & Refresh)
|
|
with pluggable database backends.
|
|
|
|
## Features
|
|
|
|
* **Complete Authentication:** User registration, email-based login, logout.
|
|
* **Token Management:**
|
|
* **JWT Access Tokens** (default: 30 min validity).
|
|
* **Opaque Refresh Tokens** securely stored in the database (default: 7 days validity).
|
|
* **User Lifecycle:**
|
|
* Email verification (via JWT token).
|
|
* Secure password reset (via secure token stored in DB).
|
|
* Account activation / deactivation.
|
|
* **Security:**
|
|
* Password hashing with `bcrypt` (configurable rounds).
|
|
* Strict password validation (uppercase, lowercase, digit, special character).
|
|
* **Flexible Architecture:**
|
|
* **Pluggable Backends:** Supports MongoDB, PostgreSQL, and SQLite out of the box.
|
|
* **Abstract Email Service:** Use the built-in SMTP implementation or plug in your own (e.g., SendGrid, AWS SES).
|
|
* **FastAPI Integration:**
|
|
* A ready-to-use `APIRouter` that exposes all necessary endpoints under the `/auth` prefix.
|
|
* Automatic handling of custom exceptions into correct HTTP responses.
|
|
|
|
---
|
|
|
|
## Installation
|
|
|
|
Install the base module and choose your "extras" based on your infrastructure.
|
|
|
|
```bash
|
|
# Base installation (core logic, no DB or email drivers)
|
|
pip install myauth --index-url [http://your-pypiserver.com/](http://your-pypiserver.com/)
|
|
|
|
# --- Installation with Extras (Recommended) ---
|
|
|
|
# To use with MongoDB
|
|
pip install "myauth[mongodb]" --index-url [http://your-pypiserver.com/](http://your-pypiserver.com/)
|
|
|
|
# To use with PostgreSQL
|
|
pip install "myauth[postgresql]" --index-url [http://your-pypiserver.com/](http://your-pypiserver.com/)
|
|
|
|
# To use the built-in SMTP email service
|
|
pip install "myauth[email]" --index-url [http://your-pypiserver.com/](http://your-pypiserver.com/)
|
|
|
|
# To combine extras (e.g., PostgreSQL + Email)
|
|
pip install "myauth[postgresql,email]" --index-url [http://your-pypiserver.com/](http://your-pypiserver.com/)
|
|
```
|
|
|
|
### Core Dependencies
|
|
|
|
The core module requires: fastapi, pydantic, pydantic-settings, python-jose[cryptography], passlib[bcrypt],
|
|
python-multipart
|
|
|
|
## Quick Start
|
|
|
|
To get started, choose one of the database options below. Each example is complete and self-contained: it sets up the
|
|
FastAPI app, the authentication service, and the related routes.
|
|
|
|
Copy-paste the example that matches your infrastructure into your main.py.
|
|
|
|
### Option 1: Quick Start with MongoDB
|
|
|
|
This example configures myauth to use MongoDB as its backend.
|
|
|
|
```Python
|
|
|
|
from fastapi import FastAPI
|
|
from my_auth import AuthService
|
|
from my_auth.api import auth_router
|
|
from my_auth.persistence.mongodb import MongoUserRepository, MongoTokenRepository
|
|
|
|
# 1. Initialize FastAPI app
|
|
app = FastAPI()
|
|
|
|
# 2. Configure repositories for MongoDB
|
|
# Make sure your connection string is correct
|
|
user_repo = MongoUserRepository(connection_string="mongodb://localhost:27017/myappdb")
|
|
token_repo = MongoTokenRepository(connection_string="mongodb://localhost:27017/myappdb")
|
|
|
|
# 3. Configure the Authentication Service
|
|
# IMPORTANT: Change this to a long, random, secret string
|
|
auth_service = AuthService(
|
|
user_repository=user_repo,
|
|
token_repository=token_repo,
|
|
jwt_secret="YOUR_SUPER_LONG_AND_SECURE_JWT_SECRET_HERE"
|
|
# email_service will be added in the next step
|
|
)
|
|
|
|
# 4. Include the authentication routes
|
|
# Endpoints like /auth/login, /auth/register are now active
|
|
app.include_router(auth_router)
|
|
|
|
|
|
@app.get("/")
|
|
def read_root():
|
|
return {"message": "Application running with MyAuth (MongoDB)"}
|
|
```
|
|
|
|
### Option 2: Quick Start with PostgreSQL
|
|
|
|
This example configures myauth to use PostgreSQL as its backend.
|
|
|
|
```Python
|
|
|
|
from fastapi import FastAPI
|
|
from my_auth import AuthService
|
|
from my_auth.api import auth_router
|
|
from my_auth.persistence.postgresql import PostgreSQLUserRepository, PostgreSQLTokenRepository
|
|
|
|
# 1. Initialize FastAPI app
|
|
app = FastAPI()
|
|
|
|
# 2. Configure repositories for PostgreSQL
|
|
# Update with your database credentials
|
|
db_config = {
|
|
"host": "localhost",
|
|
"port": 5432,
|
|
"database": "mydb",
|
|
"user": "postgres",
|
|
"password": "secret"
|
|
}
|
|
user_repo = PostgreSQLUserRepository(**db_config)
|
|
token_repo = PostgreSQLTokenRepository(**db_config)
|
|
|
|
# 3. Configure the Authentication Service
|
|
# IMPORTANT: Change this to a long, random, secret string
|
|
auth_service = AuthService(
|
|
user_repository=user_repo,
|
|
token_repository=token_repo,
|
|
jwt_secret="YOUR_SUPER_LONG_AND_SECURE_JWT_SECRET_HERE"
|
|
# email_service will be added in the next step
|
|
)
|
|
|
|
# 4. Include the authentication routes
|
|
# Endpoints like /auth/login, /auth/register are now active
|
|
app.include_router(auth_router)
|
|
|
|
|
|
@app.get("/")
|
|
def read_root():
|
|
return {"message": "Application running with MyAuth (PostgreSQL)"}
|
|
```
|
|
|
|
### Option 3: Quick Start with SQLite
|
|
|
|
This example configures myauth to use SQLite, which is ideal for development or small applications.
|
|
|
|
```Python
|
|
|
|
from fastapi import FastAPI
|
|
from my_auth import AuthService
|
|
from my_auth.api import auth_router
|
|
from my_auth.persistence.sqlite import SQLiteUserRepository, SQLiteTokenRepository
|
|
|
|
# 1. Initialize FastAPI app
|
|
app = FastAPI()
|
|
|
|
# 2. Configure repositories for SQLite
|
|
# This will create/use a file named 'auth.db' in the current directory
|
|
db_path = "./auth.db"
|
|
user_repo = SQLiteUserRepository(db_path=db_path)
|
|
token_repo = SQLiteTokenRepository(db_path=db_path)
|
|
|
|
# 3. Configure the Authentication Service
|
|
# IMPORTANT: Change this to a long, random, secret string
|
|
auth_service = AuthService(
|
|
user_repository=user_repo,
|
|
token_repository=token_repo,
|
|
jwt_secret="YOUR_SUPER_LONG_AND_SECURE_JWT_SECRET_HERE"
|
|
# email_service will be added in the next step
|
|
)
|
|
|
|
# 4. Include the authentication routes
|
|
# Endpoints like /auth/login, /auth/register are now active
|
|
app.include_router(auth_router)
|
|
|
|
|
|
@app.get("/")
|
|
def read_root():
|
|
return {"message": "Application running with MyAuth (SQLite)"}
|
|
```
|
|
|
|
## Next Step: Configure the Email Service
|
|
|
|
For email verification (/auth/verify-email) and password resets (/auth/password-reset) to work, you must provide an
|
|
email service to the AuthService.
|
|
|
|
Simply modify the AuthService initialization from the Quick Start step you chose.
|
|
|
|
### Option 1: Use the Built-in SMTP Service
|
|
|
|
This is the simplest option if you have an SMTP server (like Gmail, SendGrid SMTP, etc.). Remember to install the extra:
|
|
pip install "myauth[email]"
|
|
|
|
```Python
|
|
|
|
# ... (keep your app and repository config from the Quick Start)
|
|
|
|
from my_auth.email.smtp import SMTPEmailService
|
|
|
|
# 1. Configure the email service
|
|
email_service = SMTPEmailService(
|
|
host="smtp.gmail.com",
|
|
port=587,
|
|
username="your-email@gmail.com",
|
|
password="your-app-password", # Use an 'App Password' for Gmail
|
|
use_tls=True
|
|
)
|
|
|
|
# 2. Pass the email service to AuthService
|
|
auth_service = AuthService(
|
|
user_repository=user_repo, # From Quick Start
|
|
token_repository=token_repo, # From Quick Start
|
|
email_service=email_service, # Add this line
|
|
jwt_secret="YOUR_SUPER_LONG_AND_SECURE_JWT_SECRET_HERE"
|
|
)
|
|
|
|
# ... (keep 'app.include_router(auth_router)')
|
|
```
|
|
|
|
### Option 2: Create a Custom Email Service
|
|
|
|
If you use a third-party service (like AWS SES, Mailgun) that requires an API, you can implement your own.
|
|
|
|
```Python
|
|
|
|
# ... (keep your app and repository config from the Quick Start)
|
|
|
|
from my_auth.email.base import EmailService
|
|
|
|
|
|
# 1. Implement your custom email service
|
|
class CustomEmailService(EmailService):
|
|
def __init__(self, api_key: str):
|
|
# self.api_key = api_key
|
|
# self.client = ThirdPartyClient(api_key=api_key)
|
|
print("Custom Email Service Initialized")
|
|
|
|
def send_verification_email(self, email: str, token: str) -> None:
|
|
# Your custom logic to send an email via an API
|
|
# verification_link = f"http://localhost:8000/verify?token={token}"
|
|
print(f"Sending VERIFICATION to {email} with token {token}")
|
|
pass
|
|
|
|
def send_password_reset_email(self, email: str, token: str) -> None:
|
|
# Your custom logic to send an email via an API
|
|
# reset_link = f"http://localhost:8000/reset-password?token={token}"
|
|
print(f"Sending PASSWORD RESET to {email} with token {token}")
|
|
pass
|
|
|
|
|
|
# 2. Initialize your custom service
|
|
email_service = CustomEmailService(api_key="YOUR_API_KEY_HERE")
|
|
|
|
# 3. Pass your custom service to AuthService
|
|
auth_service = AuthService(
|
|
user_repository=user_repo, # From Quick Start
|
|
token_repository=token_repo, # From Quick Start
|
|
email_service=email_service, # Add this line
|
|
jwt_secret="YOUR_SUPER_LONG_AND_SECURE_JWT_SECRET_HERE"
|
|
)
|
|
|
|
# ... (keep 'app.include_router(auth_router)')
|
|
```
|
|
|
|
## API Endpoints Reference
|
|
|
|
The `auth_router` exposes the following endpoints under the `/auth` prefix:
|
|
|
|
```
|
|
POST /auth/register # User registration
|
|
POST /auth/login # Login (email + password)
|
|
POST /auth/logout # Logout (revokes refresh token)
|
|
POST /auth/refresh # Refresh access token
|
|
POST /auth/password-reset-request # Request password reset
|
|
POST /auth/password-reset # Reset password with token
|
|
POST /auth/verify-email-request # Request email verification
|
|
POST /auth/verify-email # Verify email with token
|
|
GET /auth/me # Get current user info
|
|
```
|
|
|
|
### Error Handling
|
|
|
|
The module uses custom exceptions that are automatically converted to the appropriate HTTP responses by FastAPI:
|
|
|
|
* `InvalidCredentialsError` → **401 Unauthorized**
|
|
* `UserAlreadyExistsError` → **409 Conflict**
|
|
* `UserNotFoundError` → **404 Not Found**
|
|
* `InvalidTokenError` → **401 Unauthorized**
|
|
* `RevokedTokenError` → **401 Unauthorized**
|
|
* `ExpiredTokenError` → **401 Unauthorized**
|
|
* `EmailNotVerifiedError` → **403 Forbidden (on login attempt)**
|
|
* `AccountDisabledError` → **403 Forbidden (on login attempt)**
|
|
|
|
## Configuration Options
|
|
|
|
All options are passed during the `AuthService` initialization:
|
|
|
|
```Python
|
|
|
|
AuthService(
|
|
user_repository: UserRepository, # Required
|
|
token_repository: TokenRepository, # Required
|
|
jwt_secret: str, # Required
|
|
jwt_algorithm: str = "HS256", # Optional
|
|
access_token_expire_minutes: int = 30, # Optional
|
|
refresh_token_expire_days: int = 7, # Optional
|
|
password_reset_token_expire_minutes: int = 15, # Optional
|
|
password_hash_rounds: int = 12, # Optional (bcrypt cost)
|
|
email_service: EmailService = None # Optional
|
|
)
|
|
```
|
|
|
|
## Appendix (Contributor & Development Details)
|
|
|
|
<details> <summary><b> Appendix A: Project Structure (src/my_auth)</b></summary>
|
|
|
|
```
|
|
my_auth/
|
|
├── __init__.py
|
|
├── models/ # Pydantic models (User, Token...)
|
|
│ ├── user.py
|
|
│ ├── token.py
|
|
│ └── email_verification.py
|
|
├── core/ # Business logic (Auth, Password, Token services)
|
|
│ ├── auth.py
|
|
│ ├── password.py
|
|
│ └── token.py
|
|
├── persistence/ # Database abstraction
|
|
│ ├── base.py # Abstract base classes
|
|
│ ├── mongodb.py
|
|
│ ├── sqlite.py
|
|
│ └── postgresql.py
|
|
├── api/ # FastAPI routes
|
|
│ └── routes.py
|
|
├── email/ # Email service
|
|
│ ├── base.py # Abstract interface
|
|
│ └── smtp.py
|
|
├── exceptions.py # Custom HTTP exceptions
|
|
└── config.py # Configuration classes (if any)
|
|
```
|
|
|
|
</details>
|
|
|
|
<details> <summary><b> Appendix B: Internal Data Models </b></summary>
|
|
|
|
### User Model
|
|
|
|
This is the internal Pydantic model used by the service.
|
|
|
|
```Python
|
|
|
|
class User:
|
|
id: str # Unique identifier
|
|
email: str # Unique, required
|
|
username: str # Required, non-unique
|
|
hashed_password: str # Bcrypt hashed
|
|
roles: list[str] # Free-form roles, no defaults
|
|
user_settings: dict # Custom user settings
|
|
is_verified: bool # Email verification status
|
|
is_active: bool # Account active status
|
|
created_at: datetime
|
|
updated_at: datetime
|
|
```
|
|
|
|
### Token Management
|
|
|
|
The module uses a unified `tokens` collection/table with a `token_type` discriminator field for all persistent tokens.
|
|
|
|
1. Access Token (JWT): 30 minutes validity, stateless, not stored in DB.
|
|
1. Refresh Token (Opaque): 7 days validity, stored in DB.
|
|
1. Password Reset Token (Random): 15 minutes validity, stored in DB.
|
|
1. Email Verification Token (JWT): Stateless, not stored in DB.
|
|
|
|
</details>
|
|
|
|
|
|
<details> <summary><b> Appendix C: Testing & Security </b></summary>
|
|
|
|
### Testing
|
|
|
|
The module is testable with `pytest`.
|
|
|
|
```Bash
|
|
|
|
pytest tests/
|
|
```
|
|
|
|
### Security Considerations
|
|
|
|
* Passwords are hashed using bcrypt with configurable rounds.
|
|
* JWT tokens are signed with HS256 (configurable).
|
|
* Refresh tokens are opaque and stored securely in the database.
|
|
* Password reset tokens are single-use, opaque, and expire quickly (15 min).
|
|
* Rate Limiting is not included and should be implemented at the application level (e.g., using `slowapi`).
|
|
* HTTPS should be enforced by the production web server (e.g., Nginx, Traefik).
|
|
|
|
</details>
|
|
|
|
## License
|
|
|
|
MIT
|