Multi-Factor Auth

Your project ships a complete TOTP second factor: an enrolment wizard, a sign-in challenge, step-up re-verification for sensitive actions, one-time recovery codes, and three security notification emails. None of it runs until you turn it on.

[auth.mfa]
# Control how many MFA factors can be enrolled at once per user.
max_enrolled_factors = 10

# Control MFA via App Authenticator (TOTP)
[auth.mfa.totp]
enroll_enabled = true
verify_enabled = true

Only TOTP is enabled. [auth.mfa.phone] ships enroll_enabled = false / verify_enabled = false, and [auth.mfa.web_authn] is commented out entirely: the Flutter UI has no screens for either.

Turn it on

ENABLE_MFA=true

It gates two things, and only two: the Multi Step Authentication row in Account → Security, and the sign-in MFA gate that routes a user with a verified factor to the challenge screen.

The recovery-code pepper

Recovery codes are never stored in plaintext. They are HMAC-SHA256'd with a pepper read from Supabase Vault under the lowercase name mfa_recovery_code_pepper, which is seeded from MFA_RECOVERY_CODE_PEPPER.

# The value must be a cryptographically random secret of at least 32 characters.
MFA_RECOVERY_CODE_PEPPER=<48 random bytes, base64>

floot create generates a value unique to your project, so local development needs nothing from you. If you set up the kit without the CLI, generate one with openssl rand -base64 48. That value is for your local stack only: never copy .env.local values to production. A hosted project gets its own pepper, created in its Vault (see below).

_pepper := app.vault_secret('mfa_recovery_code_pepper');

IF _pepper IS NULL OR char_length(_pepper) < 32 THEN
    RAISE EXCEPTION 'The mfa_recovery_code_pepper Vault secret is missing or invalid.';
END IF;

If recovery codes 500 and nothing else in your project does, look at the pepper first.

On a hosted project

[db.vault] seeding is a local-only convenience. Nothing populates the Vault on a hosted project, so a deployment with MFA_RECOVERY_CODE_PEPPER set in the dashboard's Edge Function secrets but not in the Vault fails exactly as above. Generate a fresh value (openssl rand -base64 48), not the one in your .env.local, and create it yourself (Studio → Vault, or vault.create_secret()) under the lowercase name mfa_recovery_code_pepper.

Changing it locally

supabase stop --no-backup && supabase start

The same [db.vault] block seeds four other secrets the same way (account_deletion_email_pepper, database_webhook_secret, storage_url, supabase_url), so this restart applies to all of them.

Enrolling an authenticator

Account → Security → Multi Step Authentication starts the enrolment wizard. Recovery codes are shown once, only when the just-confirmed factor is the account's first-ever verified one; second and later authenticators skip straight to success.

A user may enrol up to max_enrolled_factors authenticators (10). Unverified factors (abandoned enrolments) are never listed or counted. Removing the last verified factor turns multi-step authentication off for the account, because that is what it does.

Signing in with a second factor

When a user with a verified factor signs in, the session lands at aal1 with aal2 reachable, and the app challenges for a code. It pre-selects the authenticator last used on this device, falling back to the oldest factor, and the failed-attempt count is scoped per authenticator rather than per session, so switching authenticators resets it. After repeated failures with more than one authenticator enrolled, a guidance card suggests switching to the app the code is actually coming from, the single most common cause of "my code is wrong".

Step-up verification

Sensitive actions do not merely require an aal2 session, they require a recent verification. ensureRecentMfaVerification returns immediately if the last TOTP verification is within a 5-minute freshness window (plus a 30-second clock-skew margin) and otherwise prompts for a code.

Removing a factor passes excludeFactorId, so the guard cannot be satisfied by a verification tied to the very authenticator being removed.

Call it before your own sensitive actions:

if (await ensureRecentMfaVerification(context)) {
  // proceed
}

The database enforces the same freshness for its own dangerous actions, such as deleting an organization; see Authorization.

Recovery codes reset MFA, they do not bypass it

This is the behaviour most likely to be reported as a bug, so it is worth being blunt about.

The button is on the verification page, Use a recovery code, and warns "This will reset your MFA and sign you out of all devices." before submitting. An aal1 session is enough to redeem one: that is the whole point, since the user cannot complete a challenge, demanding aal2 here would make recovery impossible. Redeeming a code invalidates the entire batch (one code used means all six are spent), deletes every factor, verified or not, and signs the session out globally. The mfa-reset email goes out afterward; if it fails, the recovery still succeeds since it is already done by then, and the error is logged only.

Why it is built this way

A recovery code is a long-lived secret written down somewhere. If redeeming one minted an aal2 session, that piece of paper would be exactly as strong as the authenticator it is meant to back up, and an attacker who found it would get a fully-privileged session with the real second factor still quietly in place. Making redemption a loud, destructive reset (every factor gone, every session revoked, an email to the account owner) means a stolen code cannot be used silently.

Failure modes worth knowing

A malformed, unknown, already-used and revoked code all produce the identical 401, deliberately: the response must not tell an attacker which of those it was. All four count toward the lockout.

A recovery that crashed after its code was consumed is resumed on the next call without asking for (and burning) a second code, which is what the pending check is for.

Notification emails

Three emails relate to MFA, and they come from two different places.

The first two are Supabase Auth notifications, switched on in supabase/config.toml:

[auth.email.notification.mfa_factor_enrolled]
enabled = true

[auth.email.notification.mfa_factor_unenrolled]
enabled = true

Because [auth.hook.send_email] is enabled, Auth routes them through your own send-email function rather than sending them itself, which is what lets them be localized alongside the rest of your transactional email.

The third is not an Auth notification at all: the recovery-reset process renders and sends it directly, after the reset has completed. That is also why an account with no email address simply does not get it, rather than failing the recovery.

What's next?