AuthTuna 🐟

A modern async security framework for Python (FastAPI-first, framework-agnostic core). Battle-tested, batteries-included authentication, session management, RBAC, SSO, MFA, and much more.

Check Documentation at authtuna.shashstorm.in

This readme.md is so that LLM's can understand how to use the library instead of hallucinating, but it contains a decent level of docs but the docs site better.

License

This project is licensed under the GNU LGPL v3 or later. See LICENSE.txt

Below is some documentation on getting started.

Getting Started (Basic Auth & Login)
Configuration Options
FastAPI Integration
Managing Permissions
- Creating Permissions
- Permission Naming
Managing Users
Creating Roles
Batteries Included
RBAC Example
Advanced Features
Sample Backend Code
Advanced Guide & Patterns
Community & Support

Upgrading To v0.2.0

You may need to run upgrade script if you are not able to access the dashboard as the user dashboard now check the User role instead of get_current_user which was not present some versions ago and also set TRY_FULL_INITIALIZE_WHEN_SYSTEM_USER_EXISTS_AGAIN=True in .env.

Getting Started (Basic Auth & Login)

1. Install dependencies:

pip install authtuna fastapi uvicorn[standard] asyncpg aiosqlite python-dotenv

2. Create a .env file with minimum configs:

API_BASE_URL=http://localhost:8000
FERNET_KEYS=["YOUR_GENERATED_FERNET_KEY","OPTIONAL_OLDER_KEYS_FOR_COMPATIBILITY_DURING_ROTATION"]
DEFAULT_DATABASE_URI=sqlite+aiosqlite:///./authtuna.db
SECRET_KEY=your-very-secret-key

(See below for how to generate FERNET_KEYS)

3. Minimal FastAPI app:

from fastapi import FastAPI, Depends
from authtuna.middlewares.session import DatabaseSessionMiddleware
from authtuna.integrations.fastapi_integration import get_current_user

app = FastAPI()
app.add_middleware(DatabaseSessionMiddleware)

@app.get("/me")
async def me(user=Depends(get_current_user)):
    return {"id": user.id, "username": user.username, "email": user.email}

4. Run it:

uvicorn main:app --reload

Configuration Options

Required Config Keys

FERNET_KEYS: Comma-separated base64-encoded keys for encrypting sensitive data (sessions, cookies, etc).
- To generate:
```
from cryptography.fernet import Fernet
print(Fernet.generate_key().decode())
```
- Or you can also
```
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
```
  (Repeat to rotate keys, separate by commas. Oldest last in list.)
API_BASE_URL: The base URL of your API. Used for generating links in emails and security validation.

All Config Options

| Variable | Description | Required | Default | |-------------------------------|------------------------------------------------------------|----------|----------------------------------------| | APP_NAME | Name of the application. | No | AuthTuna | | ALGORITHM | JWT encryption algorithm. | No | HS256 | | API_BASE_URL | Your app's public base URL. | Yes | | | TRY_FULL_INITIALIZE_WHEN_SYSTEM_USER_EXISTS_AGAIN| Attempt to re-initialize the system user if it already exists. | No | False | | JWT_SECRET_KEY | Secret key for JWT encryption. | No | dev-secret-key-change-in-production | | ENCRYPTION_PRIMARY_KEY | Primary key for encrypting sensitive fields. | No | dev-encryption-key-change-in-production | | ENCRYPTION_SECONDARY_KEYS | Secondary keys for key rotation. | No | [] | | FERNET_KEYS | Comma-separated list of Fernet keys for session encryption. | Yes | | | DEFAULT_SUPERADMIN_PASSWORD | Default password for the superadmin user. | No | | | DEFAULT_ADMIN_PASSWORD | Default password for the admin user. | No | | | DEFAULT_SUPERADMIN_EMAIL | Default email for the superadmin user. | No | superadmin@example.com | | DEFAULT_ADMIN_EMAIL | Default email for the admin user. | No | admin@example.com | | DEFAULT_DATABASE_URI | SQLAlchemy database URI. | Yes | sqlite+aiosqlite:///./authtuna_dev.db | | DATABASE_USE_ASYNC_ENGINE | Use async SQLAlchemy drivers. | No | True | | AUTO_CREATE_DATABASE | Automatically create database tables if they don't exist. | No | True | | DATABASE_POOL_SIZE | Database connection pool size. | No | 20 | | DATABASE_MAX_OVERFLOW | Database connection pool max overflow. | No | 40 | | DATABASE_POOL_TIMEOUT | Database connection pool timeout in seconds. | No | 30 | | DATABASE_POOL_RECYCLE | Database connection pool recycle time in seconds. | No | 1800 | | DATABASE_POOL_PRE_PING | Ping the database before each connection. | No | True | | FINGERPRINT_HEADERS | List of headers to use for device fingerprinting. | No | ["User-Agent", "Accept-Language"] | | SESSION_DB_VERIFICATION_INTERVAL | Time in seconds before rechecking if a session token is still active in the database. | No | 10 | | SESSION_LIFETIME_SECONDS | Session duration in seconds. | No | 604800 | | SESSION_ABSOLUTE_LIFETIME_SECONDS | Absolute session lifetime in seconds. | No | 31536000 | | SESSION_LIFETIME_FROM | Session lifetime calculation method (last_activity or creation). | No | last_activity | | SESSION_SAME_SITE | SameSite policy for session cookies. | No | LAX | | SESSION_SECURE | Use secure cookies for sessions. | No | True | | SESSION_TOKEN_NAME | Cookie name for the session token. | No | session_token | | SESSION_COOKIE_DOMAIN | Domain for the session cookie. | No | | | LOCK_SESSION_REGION | Lock sessions to a region based on IP geolocation. | No | True | | DISABLE_RANDOM_STRING | Disable random string mismatch checks to prevent logouts in high-concurrency environments. | No | False | | RANDOM_STRING_GRACE | Grace period in seconds for accepting stored random strings. | No | 300 | | EMAIL_ENABLED | Enable or disable email features. | No | False | | SMTP_HOST | SMTP server host. | If email | | | SMTP_PORT | SMTP server port. | If email | 587 | | SMTP_USERNAME | SMTP server username. | If email | | | SMTP_PASSWORD | SMTP server password. | If email | | | DKIM_PRIVATE_KEY_PATH | Path to the DKIM private key. | If email | | | DKIM_DOMAIN | DKIM domain. | If email | | | DKIM_SELECTOR | DKIM selector. | If email | | | DEFAULT_SENDER_EMAIL | Default email address for sending emails. | No | noreply@example.com | | EMAIL_DOMAINS | Allowed email domains for user registration. | No | ["gmail.com"] | | TOKENS_EXPIRY_SECONDS | Expiry time in seconds for email tokens. | No | 3600 | | TOKENS_MAX_COUNT_PER_DAY_PER_USER_PER_ACTION | Maximum number of tokens per day per user per action. | No | 5 | | MAIL_STARTTLS | Use STARTTLS for SMTP connections. | No | True | | MAIL_SSL_TLS | Use SSL/TLS for SMTP connections. | No | False | | USE_CREDENTIALS | Use credentials for SMTP authentication. | No | True | | VALIDATE_CERTS | Validate SSL/TLS certificates. | No | True | | EMAIL_TEMPLATE_DIR | Directory for email templates. | No | authtuna/templates/email | | HTML_TEMPLATE_DIR | Directory for HTML page templates. | No | authtuna/templates/pages | | DASHBOARD_AND_USER_INFO_PAGES_TEMPLATE_DIR | Directory for dashboard and user info page templates. | No | authtuna/templates/dashboard | | GOOGLE_CLIENT_ID | Google OAuth client ID. | If Google SSO | | | GOOGLE_CLIENT_SECRET | Google OAuth client secret. | If Google SSO | | | GOOGLE_REDIRECT_URI | Google OAuth redirect URI. | If Google SSO | | | GITHUB_CLIENT_ID | GitHub OAuth client ID. | If GitHub SSO | | | GITHUB_CLIENT_SECRET | GitHub OAuth client secret. | If GitHub SSO | | | GITHUB_REDIRECT_URI | GitHub OAuth redirect URI. | If GitHub SSO | | | RPC_ENABLED | Enable or disable RPC. | No | False | | RPC_AUTOSTART | Automatically start the RPC server. | No | True | | RPC_TOKEN | RPC authentication token. | No | changeme-secure-token | | RPC_TLS_CERT_FILE | Path to the RPC TLS certificate file. | If RPC TLS | | | RPC_TLS_KEY_FILE | Path to the RPC TLS key file. | If RPC TLS | | | RPC_ADDRESS | RPC server address. | No | [::]:50051 | | `

AuthTuna

Install / Use

README