Authentication & MFA #
How login and multi-factor auth work, what you configure, and what you can't control from the server side.
Full design: auth spec §5.6.
What ships #
- Password login, with a two-phase flow when the user has MFA enabled: after the password is verified, the server issues a short-lived (5-minute), single-use MFA challenge token and requires a second factor before granting a session.
- TOTP (authenticator app) as the primary second factor.
- Email OTP as a fallback factor at the challenge screen.
- Backup codes — 8 single-use codes issued when the user enables TOTP, hashed at rest, regenerable.
- MFA-protected password reset — a user with TOTP enabled must also present an authenticator or backup code to complete a password reset (auth spec §5.5).
- CSRF origin check — cookie-authenticated form posts must come from the server's own origin,
siteUrl, orcreateManager({ options: { allowedOrigins } }). Behind a reverse proxy the check readsX-Forwarded-Proto/X-Forwarded-Host; Caddy and Fly set these by default, nginx needsproxy_set_header X-Forwarded-Proto $scheme;or dashboard form posts will 403.
There is no WebAuthn / passkey support.
MFA is user-controlled, not operator-controlled #
MFA is opt-in, per user — enabled from the app or dashboard. As an operator you cannot:
- Require MFA globally or per app. There is no server option, admin toggle, or environment variable; a login demands a second factor only if that user enabled one. If your policy requires mandatory MFA, that capability doesn't exist in this release.
- Change the 5-minute challenge-token lifetime or the lockout thresholds (5 failed challenges → a 15-minute per-user block). Fixed constants.
TOTP enrollment UI comes from whichever app calls the API; the server renders only the login-time challenge and backup-code screens.
What you are responsible for #
1. CIVILITY_AUTH_SECRET — set it and keep it stable #
It signs session tokens, password-reset/verification tokens, and the MFA challenge token, and seals admin-stored email credentials:
CIVILITY_AUTH_SECRET=$(openssl rand -hex 32)
Rotating it invalidates every in-flight session and pending MFA challenge. Generate once, store as a secret, don't churn it.
2. Configure email — the OTP fallback depends on it #
Email OTP and login codes go through the transport you configure in the admin panel (SMTP or Resend). Until then, new accounts are auto-verified and reset links are logged to the console — fine for a fresh deploy, but the email-OTP fallback can't be delivered. Configure it if you want users to have a path back in after losing their authenticator.
3. Rate limits #
The MFA challenge and email-OTP send endpoints fall under the auth rate limit (rateLimits.auth, default 10/minute), adjustable via createManager({ options: { rateLimits: { auth: … } } }). The per-user failed-challenge lockout (5 → 15 min) is always on.
Endpoint reference #
Mounted under the auth router (default /api/v1/auth). Only relevant if you're building a custom enrollment UI — the built-in dashboard already drives these.
| Method | Path | Auth | Purpose |
|---|---|---|---|
POST |
/mfa/challenge |
MFA token | Phase-2 verify (method: totp/email/backup). |
POST |
/mfa/email/send |
MFA token | Send an email OTP for an in-flight login. |
POST |
/mfa/totp/setup |
Session | Begin TOTP enrollment (returns otpauth:// URI). |
POST |
/mfa/totp/confirm |
Session | Activate TOTP; returns 8 backup codes once. |
DELETE |
/mfa/totp |
Session + password | Disable TOTP. |
POST |
/mfa/backup-codes/regenerate |
Session + TOTP code | Reissue backup codes. |
Backup codes and the otpauth:// secret are shown once at generation and never retrievable afterward — the same "copy it now" rule as invite tokens.
Support runbook (common user situations) #
- "I lost my authenticator." They use a backup code at the challenge screen (
method: backup), or the email OTP fallback if you've configured email. After getting back in, they can regenerate backup codes (requires a current TOTP code) or disable + re-enroll TOTP (requires their password). - "I lost my authenticator and my backup codes and email isn't set up." There is no operator override to clear a user's MFA. This is why configuring email transport is worthwhile — it gives users a self-service recovery path. Absent that, account recovery is out-of-band (e.g. deleting and recreating the account, losing its server-side data).
- Compromise. Rotating
CIVILITY_AUTH_SECRETinvalidates all sessions immediately (blunt but effective); per-user grant revocation is in the admin panel.
See also #
- Admin panel — email transport config, per-user grants, limits.
- Auth spec §5.6 — the full MFA design.
- Manual VPS guide —
CIVILITY_AUTH_SECRETin the systemd env file.