https://github.com/rennf93/two-fast-auth
FastAPI middleware that provides seamless two-factor authentication implementation. It integrates with FastAPI to offer robust 2FA protection for your application routes.
https://github.com/rennf93/two-fast-auth
2fa fastapi middleware python security
Last synced: about 1 year ago
JSON representation
FastAPI middleware that provides seamless two-factor authentication implementation. It integrates with FastAPI to offer robust 2FA protection for your application routes.
- Host: GitHub
- URL: https://github.com/rennf93/two-fast-auth
- Owner: rennf93
- License: mit
- Created: 2025-01-31T16:52:55.000Z (over 1 year ago)
- Default Branch: master
- Last Pushed: 2025-03-08T11:03:19.000Z (over 1 year ago)
- Last Synced: 2025-04-06T04:38:20.321Z (about 1 year ago)
- Topics: 2fa, fastapi, middleware, python, security
- Language: Python
- Homepage: https://rennf93.github.io/two-fast-auth/
- Size: 773 KB
- Stars: 17
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
---
[](https://badge.fury.io/py/two-fast-auth)
[](https://github.com/rennf93/two-fast-auth/actions/workflows/release.yml)
[](https://opensource.org/licenses/MIT)
[](https://github.com/rennf93/two-fast-auth/actions/workflows/ci.yml)
[](https://github.com/rennf93/two-fast-auth/actions/workflows/code-ql.yml)
[](https://github.com/rennf93/two-fast-auth/actions/workflows/docs.yml)
[](https://pepy.tech/project/two-fast-auth)
`two-fast-auth` is a FastAPI middleware that provides seamless two-factor authentication implementation. It integrates with FastAPI to offer robust 2FA protection for your application routes.
---
## Documentation
📚 [Full Documentation](https://rennf93.github.io/two-fast-auth/) - Comprehensive technical documentation and API reference
## Features
- **QR Code Generation**: Automatic QR code creation for authenticator apps
- **TOTP Verification**: Time-based one-time password validation
- **Recovery Codes**: Secure recovery code generation and management
- **Optional Secret Encryption**: Securely store and verify 2FA secrets
- **Middleware Integration**: Easy integration with FastAPI routes
## Installation
To install `two-fast-auth`, use pip:
```bash
pip install two-fast-auth
```
## Basic Usage
```python
from fastapi import FastAPI
from two_fast_auth import TwoFactorMiddleware, TwoFactorAuth
app = FastAPI()
async def get_user_secret(user_id: str) -> str:
# Implement your logic to retrieve user's secret from database
return "user_stored_secret" # Replace with actual DB lookup
app.add_middleware(
TwoFactorMiddleware,
get_user_secret_callback=get_user_secret,
excluded_paths=["/docs", "/redoc"],
header_name="X-2FA-Code",
encryption_key="your-key-here" # Optional
)
@app.get("/protected-route")
async def protected_route():
return {"message": "2FA protected content"}
```
## Configuration Options
### TwoFactorAuth Parameters
| Parameter | Default | Description |
|---------------------|--------------|-----------------------------------------------------------------------------|
| `secret` | Auto-generated| Base32 secret for TOTP generation |
| `qr_fill_color` | "black" | QR code foreground color |
| `qr_back_color` | "white" | QR code background color |
| `issuer_name` | "2FastAuth" | Name displayed in authenticator apps |
### TwoFactorMiddleware Parameters
| Parameter | Default | Description |
|---------------------|----------------------|-----------------------------------------------------------------------------|
| `encryption_key` | None | Encryption key for securing 2FA secrets (Fernet-compatible key) |
| `excluded_paths` | ["/login", "/setup-2fa"] | Paths that bypass 2FA verification |
| `header_name` | "X-2FA-Code" | Request header containing 2FA verification code |
## Advanced Configuration
```python
# Generate and encrypt secret
secret = TwoFactorAuth().secret
encrypted_secret = TwoFactorAuth.encrypt_secret(
secret,
encryption_key="your-key-here"
)
# Store encrypted secret in database
async def get_user_secret(user_id: str) -> str:
return await fetch_encrypted_secret_from_db(user_id)
# Middleware with encrypted secrets
app.add_middleware(
TwoFactorMiddleware,
get_user_secret_callback=get_user_secret,
encryption_key="your-key-here",
excluded_paths=["/healthcheck"]
)
```
## Contributing
Contributions are welcome! Please open an issue or submit a pull request on GitHub.
## License
MIT License - See [LICENSE](https://github.com/rennf93/two-fast-auth/blob/main/LICENSE) for details
## Author
**Renzo Franceschini**
- [GitHub Profile](https://github.com/rennf93)
- [Email](mailto:rennf93@gmail.com)
## Acknowledgements
- [Cryptography](https://cryptography.io/)
- [FastAPI](https://fastapi.tiangolo.com/)
- [PyOTP](https://pyauth.github.io/pyotp/)
- [qrcode](https://github.com/lincolnloop/python-qrcode)