Connected apps with 3rd-party data hosts jsr.io/@civility
5.6 kB · 84 lines
Markdown
at main

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, or createManager({ options: { allowedOrigins } }). Behind a reverse proxy the check reads X-Forwarded-Proto/X-Forwarded-Host; Caddy and Fly set these by default, nginx needs proxy_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_SECRET invalidates all sessions immediately (blunt but effective); per-user grant revocation is in the admin panel.

See also #