https://github.com/igorbenav/fastsecure
A modern, flexible authentication system for FastAPI applications with support for multiple authentication methods and strategies.
https://github.com/igorbenav/fastsecure
auth authentication authorization fastapi jwt session
Last synced: 7 months ago
JSON representation
A modern, flexible authentication system for FastAPI applications with support for multiple authentication methods and strategies.
- Host: GitHub
- URL: https://github.com/igorbenav/fastsecure
- Owner: igorbenav
- Created: 2025-02-05T05:15:34.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-02-11T22:29:34.000Z (over 1 year ago)
- Last Synced: 2025-02-11T23:31:53.166Z (over 1 year ago)
- Topics: auth, authentication, authorization, fastapi, jwt, session
- Language: Python
- Homepage:
- Size: 162 KB
- Stars: 4
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# FastSecure
A modern, flexible authentication system for FastAPI applications with support for multiple authentication methods and strategies.
## Table of Contents
- [Features](#features)
- [Installation](#installation)
- [Core Concepts](#core-concepts)
- [Basic Usage Guide](#basic-usage-guide)
- [Setting Up JWT Authentication](#setting-up-jwt-authentication)
- [Setting Up Session Authentication](#setting-up-session-authentication)
- [Setting Up OAuth Authentication](#setting-up-oauth-authentication)
- [Advanced Usage Guide](#advanced-usage-guide)
- [Combining Authentication Methods](#combining-authentication-methods)
- [Custom Authentication Providers](#custom-authentication-providers)
- [Storage Backends](#storage-backends)
- [Security Best Practices](#security-best-practices)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)
- [License](#license)
> [!WARNING]
> FastSecure is still experimental.
## Features
- 🔐 **Multiple Authentication Methods**
- JWT tokens with refresh token support and flexible configuration
- Session-based authentication with configurable storage backends
- OAuth 2.0 providers (Google, GitHub) with standardized user info
- Easy to extend with custom authentication providers
- 🔄 **Flexible Authentication Strategies**
- Use single or multiple authentication methods
- Support for AND logic (require all methods)
- Support for OR logic (allow any method)
- Optional authentication methods
- Path-based authentication requirements
- 🗄️ **Session Storage Options**
- In-memory storage for development
- Redis backend for distributed systems
- Database backend (SQLAlchemy) for persistence
- Easy to implement custom storage backends
- 🛡️ **Security Features**
- Token expiration and refresh
- Session timeout and cleanup
- Concurrent session limits
- Scope-based authorization
- IP tracking and user agent logging
## Installation
1. Install using pip:
```bash
pip install fastsecure
```
2. Install using uv or poetry:
```bash
uv add fastsecure
```
```bash
poetry add fastsecure
```
## Core Concepts
Before diving into the implementation, let's understand the core concepts:
### Authentication Manager
The `AuthenticationManager` is the central component that:
- Manages authentication providers
- Handles authentication strategies
- Enforces authentication requirements
- Coordinates the authentication flow
### Authentication Providers
Providers implement specific authentication methods:
- JWT tokens
- Sessions
- OAuth
- Custom methods
### Authentication Strategies
Strategies determine how multiple authentication methods are combined:
- `AuthStrategy.ANY`: Any provider can authenticate (OR logic)
- `AuthStrategy.ALL`: All providers must authenticate (AND logic)
### Authentication Requirements
Requirements specify which authentication methods are needed for specific paths:
- Required providers
- Optional providers
- Authentication strategy
- Required scopes
## Basic Usage Guide
### Setting Up JWT Authentication
1. **Create a Basic FastAPI Application**
```python
from fastapi import FastAPI, Depends, HTTPException
from fastsecure import AuthenticationManager, JWTAuthenticationProvider
app = FastAPI()
```
2. **Initialize Authentication Manager and JWT Provider**
```python
# Initialize authentication
auth_manager = AuthenticationManager()
# Configure JWT provider
jwt_auth = JWTAuthenticationProvider(
secret_key="your-secret-key", # Use a secure key in production!
access_token_expire_minutes=30,
refresh_token_expire_days=7
)
# Register the provider
auth_manager.register_provider("jwt", jwt_auth)
```
3. **Create Authentication Dependency**
```python
from fastapi import Request
from typing import Optional
async def requires_auth(request: Request, path: Optional[str] = None) -> dict:
"""
FastAPI dependency for authentication requirements.
Args:
request: The FastAPI request object
path: Optional path override for authentication requirements
Returns:
Authentication result if successful
Raises:
HTTPException: If authentication fails
"""
# Get authentication data from request headers
auth_header = request.headers.get("Authorization")
if not auth_header:
raise HTTPException(status_code=401, detail="No authentication provided")
# Parse Bearer token
try:
scheme, token = auth_header.split()
if scheme.lower() != "bearer":
raise HTTPException(status_code=401, detail="Invalid authentication scheme")
except ValueError:
raise HTTPException(status_code=401, detail="Invalid authorization header")
# Authenticate using the manager
result = await auth_manager.authenticate(
path or request.url.path,
{"jwt": {"access_token": token}}
)
if not result.success:
raise HTTPException(
status_code=401,
detail="Authentication failed",
headers={"WWW-Authenticate": "Bearer"}
)
return result
```
4. **Configure Protected Routes**
```python
# Add authentication requirement for protected paths
auth_manager.add_requirement(
"/api/protected/*", # Path pattern
providers=["jwt"], # Required providers
scopes=["read"] # Required scopes (optional)
)
```
5. **Implement Login and Protected Routes**
```python
from pydantic import BaseModel
class LoginCredentials(BaseModel):
username: str
password: str
@app.post("/api/auth/login")
async def login(credentials: LoginCredentials):
# Validate credentials (implement your own validation)
user_id = validate_credentials(credentials)
# Authenticate with JWT provider
result = await auth_manager.authenticate(
"/api/protected/data",
{"jwt": {
"user_id": user_id,
"scopes": ["read", "write"]
}}
)
if not result.success:
raise HTTPException(401, "Authentication failed")
return {
"access_token": result.access_token,
"refresh_token": result.refresh_token,
"token_type": "Bearer",
"expires_at": result.expires_at
}
@app.get("/api/protected/data")
async def protected_data(auth = Depends(requires_auth)):
return {
"message": "Authenticated!",
"user_id": auth.user_id,
"scopes": auth.metadata.get("scopes", [])
}
```
### Setting Up Session Authentication
1. **Choose a Storage Backend**
```python
from fastsecure import (
SessionAuthenticationProvider,
RedisSessionStore,
DatabaseSessionStore
)
# For development (in-memory)
session_auth = SessionAuthenticationProvider()
# For production with Redis
session_auth = SessionAuthenticationProvider(
session_store=RedisSessionStore("redis://localhost"),
session_timeout_minutes=60,
max_sessions_per_user=3,
cleanup_expired=True
)
```
2. **Configure Session Authentication**
```python
# Register the provider
auth_manager.register_provider("session", session_auth)
# Add requirements
auth_manager.add_requirement(
"/api/user/*",
providers=["session"]
)
```
3. **Implement Session Login**
```python
@app.post("/api/auth/session/login")
async def session_login(
credentials: LoginCredentials,
request: Request
):
user_id = validate_credentials(credentials)
result = await auth_manager.authenticate(
"/api/user/profile",
{"session": {
"user_id": user_id,
"ip_address": request.client.host,
"user_agent": request.headers.get("user-agent"),
"scopes": ["user:read"]
}}
)
if not result.success:
raise HTTPException(401, "Authentication failed")
response = JSONResponse({
"message": "Logged in successfully",
"user_id": user_id
})
# Set session cookie
response.set_cookie(
"session_id",
result.session_id,
httponly=True,
secure=True,
samesite="lax",
expires=result.expires_at
)
return response
```
### Setting Up OAuth Authentication
1. **Configure OAuth Providers**
```python
from fastsecure import GoogleAuthProvider, GitHubAuthProvider
# Google Sign-In
google_auth = GoogleAuthProvider(
client_id="your-client-id",
client_secret="your-client-secret",
redirect_uri="http://localhost:8000/auth/google/callback"
)
# GitHub Sign-In
github_auth = GitHubAuthProvider(
client_id="your-client-id",
client_secret="your-client-secret",
redirect_uri="http://localhost:8000/auth/github/callback"
)
# Register providers
auth_manager.register_provider("google", google_auth)
auth_manager.register_provider("github", github_auth)
```
2. **Implement OAuth Flow**
```python
@app.get("/auth/google/login")
async def google_login():
authorization_url = google_auth.get_authorization_url(
state="random-secure-state" # Implement secure state handling
)
return RedirectResponse(authorization_url)
@app.get("/auth/google/callback")
async def google_callback(code: str, state: str):
# Validate state
validate_oauth_state(state)
result = await auth_manager.authenticate(
"/api/user/profile",
{"google": {"code": code}}
)
if not result.success:
raise HTTPException(401, "Authentication failed")
# Get user info from result
user_info = result.metadata["user_info"]
return {
"message": "Logged in with Google",
"email": user_info["email"],
"name": user_info["name"],
"access_token": result.access_token
}
```
## Advanced Usage Guide
### Combining Authentication Methods
1. **Require Multiple Methods (AND Strategy)**
```python
# Require both JWT and session authentication
auth_manager.add_requirement(
"/api/admin/*",
providers=["jwt", "session"],
strategy=AuthStrategy.ALL,
scopes=["admin"]
)
# Example request handler
@app.post("/api/admin/action")
async def admin_action(auth = Depends(auth_manager.requires_auth)):
if "admin" not in auth.metadata.get("scopes", []):
raise HTTPException(403, "Insufficient permissions")
return {"message": "Admin action successful"}
```
2. **Allow Alternative Methods (OR Strategy)**
```python
# Allow any authentication method
auth_manager.add_requirement(
"/api/user/*",
providers=["jwt", "session", "google"],
strategy=AuthStrategy.ANY
)
```
3. **Optional Authentication**
```python
# Add optional authentication methods
auth_manager.add_requirement(
"/api/public/*",
providers=["jwt"],
optional_providers=["session", "google"]
)
```
### Custom Authentication Providers
1. **Create a Custom Provider**
```python
from fastsecure import AuthenticationProvider, AuthenticationResult
from typing import Dict, Any, Set
class APIKeyAuthProvider(AuthenticationProvider):
def __init__(self, api_keys: Dict[str, str]):
self.api_keys = api_keys
def get_required_credentials(self) -> Set[str]:
return {"api_key"}
async def authenticate(
self,
credentials: Dict[str, Any]
) -> AuthenticationResult:
api_key = credentials.get("api_key")
if api_key not in self.api_keys:
return AuthenticationResult(
success=False,
provider=self.provider_name,
metadata={"error": "Invalid API key"}
)
return AuthenticationResult(
success=True,
provider=self.provider_name,
user_id=self.api_keys[api_key],
metadata={"api_key": api_key}
)
async def validate_authentication(
self,
auth_data: Dict[str, Any]
) -> bool:
return auth_data.get("api_key") in self.api_keys
```
2. **Register and Use Custom Provider**
```python
# Initialize with API keys
api_key_auth = APIKeyAuthProvider({
"key1": "user1",
"key2": "user2"
})
# Register provider
auth_manager.register_provider("apikey", api_key_auth)
# Add requirement
auth_manager.add_requirement(
"/api/service/*",
providers=["apikey"]
)
```
### Storage Backends
1. **Implement Custom Session Storage**
```python
from fastsecure import SessionStore
from typing import Dict, Any, List, Optional
from datetime import datetime
class CustomSessionStore(SessionStore):
async def create_session(
self,
user_id: int,
session_id: str,
expires_at: datetime,
metadata: Dict[str, Any]
) -> bool:
# Implement session creation
pass
async def get_session(
self,
session_id: str
) -> Optional[Dict[str, Any]]:
# Implement session retrieval
pass
async def update_session(
self,
session_id: str,
metadata: Dict[str, Any]
) -> bool:
# Implement session update
pass
async def delete_session(
self,
session_id: str
) -> bool:
# Implement session deletion
pass
async def get_user_sessions(
self,
user_id: int
) -> List[Dict[str, Any]]:
# Implement user sessions retrieval
pass
```
## Security Best Practices
1. **JWT Security**
- Use strong secret keys
- Set appropriate token expiration times
- Implement token refresh securely
- Use HTTPS for token transmission
2. **Session Security**
- Enable secure cookie attributes
- Implement session timeout
- Limit concurrent sessions
- Clean up expired sessions
3. **OAuth Security**
- Validate OAuth state parameter
- Use HTTPS for callbacks
- Validate token scopes
- Handle user data securely
4. **General Security**
- Implement rate limiting
- Use secure password handling
- Log security events
- Regular security audits
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Contact
Igor Benav – [@igorbenav](https://x.com/igorbenav) – igormagalhaesr@gmail.com
[github.com/igorbenav](https://github.com/igorbenav/)