2FA — two-factor authentication¶
Vesana supports two 2FA methods. Every user decides for themselves which one to set up under "My account" — unless an enforcement rule mandates a minimum strength (see below). Email 2FA has been removed (weakest factor, SMTP-dependent).
The two methods¶
| Method | How | Strength |
|---|---|---|
| Authenticator app (TOTP) | Standard authenticator (e.g. Google Authenticator, Authy), QR code during setup | Strong — works offline, no mail account access needed |
| Security key (WebAuthn/passkey) | Hardware key or platform passkey (e.g. Windows Hello, Touch ID) | The strongest tier — hardware-bound, phishing-resistant |
An account can hold both methods at once: registering a security key on top of the authenticator does not take the authenticator away. The login screen then offers what the account actually has — security key, authenticator code or backup code — with a switch in case the key is not at hand. After 5 failed login attempts a 30-minute lockout kicks in.
Up to v1.9.441 a registered passkey locked the account out
Login then demanded the passkey but only knew the field for the authenticator code — every entry ended in an error, and only a super admin reset helped. On older versions, set up passkeys only after updating.
Setting up the authenticator app (TOTP)¶
"My account → 2FA → Authenticator app":
- Scan the QR code with the app (or type in the secret manually)
- Enter the displayed 6-digit code to confirm → 2FA active
Setting up a security key (WebAuthn)¶
"My account → 2FA → Security key":
- Plug in/tap the hardware key or confirm the platform passkey
- Complete registration → 10 backup codes are shown once — download or print them immediately
Backup codes are mandatory with WebAuthn (no setup without them) — they're your safety net if the key is ever lost.
The authenticator app now gets backup codes too (from v1.9.442): activating it generates ten codes and shows them once, as does the dialog that enforces 2FA setup. Existing codes are left untouched. Under "My account → Security" you see how many codes are left, with a button to generate more — including for accounts that never had any. Before that, an account with only an authenticator app had no fallback at all: losing the phone meant losing the account.
Regenerating backup codes requires a fresh factor proof
Generating new backup codes — like every sensitive action — requires an identity confirmation within the last 15 minutes (passkey, authenticator code or password); otherwise a stolen login cookie alone could rotate all your codes.
WebAuthn must be actively configured on the instance (a relying-party ID on file), otherwise the option won't appear in the 2FA settings at all, nor as a selectable factor in enforcement rules.
Factor strength hierarchy¶
A stronger factor automatically satisfies any weaker requirement:
So a user set up with WebAuthn also satisfies a rule that requires "at least TOTP". Legacy rules using the removed "email" tier behave like "any".
2FA enforcement rules (Admin → Login & Security → 2FA & Sessions)¶
Instead of switching 2FA on or off globally, you create targeted enforcement rules — for a single user, a whole role, everyone with a given permission, or an entire tenant:
| Field | Meaning |
|---|---|
| Name / description | free text |
| Selector type | Single user / role / permission / tenant |
| Selector value | the concrete user, role, permission, or tenant |
| Factor required | Any / authenticator app (TOTP) / security key (WebAuthn) |
| Grace period (days) | how long an affected user has before login gets blocked |
| Active | toggle |
While creating a rule, a live impact preview shows how many active users the rule would affect, how many of them haven't set up a matching 2FA yet (and thus fall into the grace period), and how many are currently mid-grace already.
When several rules match the same user¶
The strictest wins: by factor strength (WebAuthn > TOTP > any), and on a tie, the shorter grace period.
What happens for the affected user¶
- First login after the rule takes effect → a notice that 2FA needs to be set up, with the remaining grace period
- Set up within the window → normal login continues
- Window expires without setup → login is blocked until the required factor is set up
Exemptions¶
Per rule, you can list individual users as exemptions (with an optional internal reason, e.g. "service account, no interactive login"). Exempted users ignore that specific rule — other rules that also match them still apply.
Self-disable blocked while a rule is active¶
A user can't disable their own 2FA as long as an enforcement rule applies to them (even during the grace period). A super admin can still reset it in an emergency (see admin override below).
Admin override¶
If a user is completely locked out (no authenticator, no security key, no backup codes left):
Admin → Users & Tenants → Users → affected user → Reset 2FA (icon in the row or context menu)
Removes the authenticator app, all passkeys and all backup codes of the user (complete from v1.9.437 — before, a passkey of the lost device stayed valid) and logs out all of their sessions. You are asked to confirm with the consequences listed, and afterwards told what was removed. An audit entry is written; the user sets 2FA up again at the next login (and is again subject to any enforcement rule that applies to them). Your own 2FA cannot be reset this way (use Settings → Security or a second super admin); SSO accounts are excluded.
Failed attempts and login¶
- Five wrong codes lock 2FA login for 30 minutes (during setup as well as at login).
- A TOTP code is valid exactly once — the same code does not confirm a second login (from v1.9.437).
- The code field carries a field name so password managers (Bitwarden etc.) fill the code in automatically.
- If the server does not respond during code entry, the page says exactly that — not "wrong code".
- When an enforcement rule applies, the server blocks everything until setup is done; the setup dialog appears immediately in both the user and the admin portal.
Recommendation¶
- Super Admin, Admin: enforce a security key, or at least an authenticator app, via an enforcement rule
- Operator: authenticator app recommended
- Viewer: optional, depending on the tenant's data sensitivity
Next¶
- Users & tenants
- Admin access & split container — an additional network-level layer for the entire admin area