Authentication

Overview

Authentication is built on Flask-Security-Too 5.9. Out of the box you get:

Email login and registration
Password change, with a 12 character minimum
TOTP two-factor authentication with recovery codes
Passkeys (WebAuthn), as a first factor or a second one
Google and GitHub OAuth
Roles, with an admin UI for users and roles
Server-side sessions and CSRF protection on every POST, PUT and DELETE

Password recovery and email confirmation are off by default because they need a mail server. Turn them on in enferno/settings.py (SECURITY_RECOVERABLE, SECURITY_CONFIRMABLE) and set the mail variables below.

Configuration

Security behavior lives in enferno/settings.py. .env holds the secrets, which setup.sh generates:

SECRET_KEY=...
SECURITY_PASSWORD_SALT=...
SECURITY_TOTP_SECRETS=...

# Mail, for password recovery and confirmation
MAIL_SERVER=smtp.example.com
MAIL_USERNAME=...
MAIL_PASSWORD=...
MAIL_PORT=465
MAIL_USE_SSL=True
MAIL_USE_TLS=False
SECURITY_EMAIL_SENDER=noreply@example.com

The mail defaults are port 465 with SSL on and TLS off. For a provider that uses STARTTLS, set MAIL_PORT=587, MAIL_USE_SSL=False and MAIL_USE_TLS=True. Rerunning setup.sh keeps existing secrets, so sessions, password hashes and 2FA keep working.

OAuth

GOOGLE_AUTH_ENABLED=true
GOOGLE_OAUTH_CLIENT_ID=your_client_id
GOOGLE_OAUTH_CLIENT_SECRET=your_client_secret

GITHUB_AUTH_ENABLED=true
GITHUB_OAUTH_CLIENT_ID=your_client_id
GITHUB_OAUTH_CLIENT_SECRET=your_client_secret

Google: https://your-domain.com/login/google/authorized
GitHub: https://your-domain.com/login/github/authorized

Google requests the profile and email scopes, GitHub user:email. For local testing over plain HTTP, set OAUTHLIB_INSECURE_TRANSPORT=1.

Protecting Routes

Protect a whole blueprint in before_request instead of decorating each route:

from flask import Blueprint
from flask_security import auth_required, roles_required

bp = Blueprint("reports", __name__)


@bp.before_request
@auth_required("session")
@roles_required("admin")
def before_request():
    pass

For a single route, @roles_accepted("editor", "admin") allows any of the listed roles.

Users and Roles

uv run flask install                            # Create the first admin
uv run flask create -e <email> -p <password>    # Create a user
uv run flask add-role -e <email> -r <role>      # Grant a role
uv run flask reset -e <email> -p <password>     # Reset a password

Admins can also manage users and roles at /users/ and /roles/. Every change is recorded in the activity log at /activities/.

Sessions

Sessions are stored server-side, in the database by default or in Redis with setup.sh --full. They last one hour, and Flask-Security asks for the password again before sensitive changes if the login is older than 60 minutes. Cookie flags come from .env:

SESSION_COOKIE_SECURE=true      # Required behind HTTPS; setup.sh --docker sets it
SESSION_COOKIE_HTTPONLY=true
SESSION_COOKIE_SAMESITE=Lax

API Requests

The JSON API uses the same session as the pages (SECURITY_API_ENABLED_METHODS = ["session"]). Pages that extend layout.html send the CSRF token with every axios request. Plain HTML forms need:

<input type="hidden" name="csrf_token" value="{{ csrf_token() }}">

Logout is POST only, so use a form posting to /logout, never a link.

Troubleshooting

2FA codes rejected: TOTP depends on the clock. Check the server and phone time are in sync.
OAuth redirect mismatch: the callback URL registered with the provider must match the domain and scheme exactly.

Getting Started

Core Features

Development

Overview

Configuration

OAuth

Protecting Routes

Users and Roles

Sessions

API Requests

Troubleshooting

​Overview

​Configuration

​OAuth

​Protecting Routes

​Users and Roles

​Sessions

​API Requests

​Troubleshooting

Overview

Configuration

OAuth

Protecting Routes

Users and Roles

Sessions

API Requests

Troubleshooting