Two-factor authentication¶
VisuAuth ships TOTP (authenticator-app) two-factor as part of the end-user surface: enrolment, the sign-in challenge, and recovery codes. It's driven by ASP.NET Core Identity's own token providers — VisuAuth adds the pages, the QR code, and the admin-side reset.
Available whenever the backend declares SupportsTwoFactor, which the
Identity adapter does. Entra-backed deployments
declare it false — Microsoft owns authenticator enrolment there — so the pages
and controls hide themselves rather than half-working.
Pages¶
| Route | Purpose | Access |
|---|---|---|
/visuauth/two-factor/setup |
Pair an authenticator app | signed-in user |
/visuauth/two-factor/verify |
The challenge during sign-in | anonymous |
/visuauth/two-factor/recovery-codes |
View / regenerate recovery codes | signed-in user |
The challenge page is deliberately anonymous: it runs mid-sign-in, after the password succeeded but before the user holds a full identity. Requiring authentication there would break the flow it exists to complete. Setup and recovery codes require a signed-in user, as you'd expect — see Securing the admin for how those levels survive a global fallback policy.
Enrolment¶
/visuauth/two-factor/setup renders the shared secret as an inline SVG QR code
(via QRCoder — no external image service, no outbound call), plus the manual
key for authenticator apps that prefer typing it. Scanning it and entering one
generated code completes enrolment and reveals the recovery codes.
The label your users see in their authenticator app comes from
TwoFactorIssuerOptions:
builder.Services.Configure<TwoFactorIssuerOptions>(options =>
{
options.Issuer = "Acme Corp"; // defaults to "VisuAuth"
});
Set this to your product name before shipping. It's baked into the otpauth://
URI at enrolment time, so changing it later doesn't rename existing enrolments —
users who already paired keep seeing the old label.
Recovery codes¶
Generated at enrolment and shown once. /visuauth/two-factor/recovery-codes
lets a signed-in user regenerate them, which invalidates the previous set.
Treat them as password-equivalent: each one is single-use and bypasses the
authenticator entirely.
Resetting a user's 2FA as an operator¶
From the user's detail page in the admin UI, Reset two-factor disables 2FA and resets the authenticator key, so the user enrols again from scratch. Use it when someone loses their device and their recovery codes.
This is capability-gated on SupportsTwoFactorReset. Entra declares it true
even though it declares SupportsTwoFactor false — the admin can wipe a
directory user's registered authentication methods through Graph, forcing
re-enrolment through Microsoft's own surfaces. It needs the
UserAuthenticationMethod.ReadWrite.All application permission.
Interaction with the mobile API¶
POST /visuauth/api/auth/login answers 401 with
"Two-factor authentication is required." instead of issuing a token, so a
native client can tell a 2FA requirement apart from a wrong password.
The REST channel can't complete the challenge. There is no
api/auth/two-factorendpoint —/login,/register, and/refreshare the whole surface. A native app whose users have 2FA enabled should use the WebView deep-link flow, which runs the real/visuauth/two-factor/verifypage and hands back a token at the end. Purely-REST clients only work for accounts without 2FA.Capture note. This page has no screenshots yet — the setup / challenge captures are tracked in
docs/CAPTURE_CHECKLIST.md.