Skip to content

2FA — Two-factor authentication

Vesana uses email-based 2FA: after login password, an 8-digit code arrives at the user's email.

Enable

/profile → Enable 2FA:

  1. Click „Enable 2FA"
  2. Test code via mail is sent
  3. Enter code → 2FA active

With 2FA active: every login asks for password + code. Code valid 10 minutes.

Codes

  • 8 digits (was 6)
  • SHA256 hash in DB, plaintext never stored
  • Single-use — once used, can't be reused

Lockout

5 failed attempts → 30 minute lockout (HTTP 429 with Retry-After).

Fields in users: - two_fa_email_code_hash - two_fa_attempts - two_fa_lockout_until

(Migration 013)

After 30 minutes the lockout ends, counter at 0.

Recovery

Recovery codes

On enabling 2FA, 10 recovery codes are generated. Shown once, download or print immediately. If you lose email access, one recovery code logs in.

Each recovery code is single-use. When all spent: regenerate in /profile (old ones invalid).

Admin override

If a user is fully locked out (no email access, no recovery codes):

/admin/users → User → Reset 2FA

Super admin or custom role with user.reset_2fa only. Audit entry written.

SSO alternative

Currently email-2FA is the only second factor besides password. SSO features (OIDC, SAML, LDAP) were removed in v0.16.x — for SSO use a reverse proxy with own auth front (see TLS / reverse proxy).

Recommendation

  • Super admin: 2FA mandatory
  • Tenant admin: 2FA mandatory
  • Operator: 2FA recommended
  • Viewer: 2FA optional

Mandatory 2FA per role activatable in /admin/roles → Role → 2FA required = true.

Mobile app + 2FA

After password the app asks for the 2FA code. Code arrives via mail (same mechanism as web).

In the app the 2FA step is visually optimized — bigger input fields, auto-submit at 8 chars.

Next