Login MFA

Vault enforces multi-factor authentication at login time across nearly every auth method. The MFA orchestrator is vault/login_mfa.go (3,122 lines), with shared types under helper/identity/mfa/.

Purpose

Require a second proof factor — TOTP, Duo, Okta, PingID, or WebAuthn — for some or all login attempts, with the policy decided centrally rather than per-auth-method.

Methods

Method	Provider	Notes
TOTP	Built-in (RFC 6238)	Stores per-user secrets in identity store.
Duo	Duo Security API	Push or passcode.
Okta Verify	Okta API	Push.
PingID	Ping Identity API	Push or OTP.
WebAuthn	FIDO2 keys (browser)	Public-key based, hardware tokens.

The list is in helper/identity/mfa/mfa.go and used to validate Method.Type on configuration.

Flow

sequenceDiagram
    participant C as Client
    participant Core as Core.HandleRequest
    participant MFA as login_mfa.go
    participant ID as Identity store
    participant TS as Token store
    C->>Core: POST /auth/<mount>/login
    Core->>ID: resolve entity from auth response Alias
    Core->>MFA: enforcement.Match(entity, mount)?
    alt MFA required
        MFA-->>Core: mfa_request_id (no token)
        Core-->>C: { auth: { mfa_requirement } }
        C->>Core: POST /sys/mfa/validate { mfa_request_id, payload }
        Core->>MFA: validate factor
        MFA-->>Core: ok
        Core->>TS: mint token
    else no MFA
        Core->>TS: mint token
    end
    Core-->>C: token

The first response carries an mfa_requirement block with the IDs of every method that must succeed (could be more than one). The client posts proof to sys/mfa/validate and only then receives a token.

Configuration

MFA configuration lives at:

• identity/mfa/method/<type>/<id> — the method (per type).
• identity/mfa/login-enforcement/<name> — which entities/groups/mounts/auth-types require which methods.

Both live under identity/, so they're owned by the identity store. CRUD is exposed via vault/login_mfa.go paths.

vault write identity/mfa/method/totp/myotp issuer=Vault qr_size=200
vault write identity/mfa/login-enforcement/admins \
    mfa_method_ids="<id>" \
    auth_method_accessors="<userpass-accessor>"

CE vs Enterprise

OSS supports MFA on the login path (auth/<mount>/login). Enterprise additionally supports step-up MFA where individual policy paths can require MFA before allowing the operation. The CE file vault/login_mfa_ce.go is the corresponding stub for those endpoint-level enforcements.

TOTP self-enrollment

Users with update on identity/mfa/method/totp/<id>/admin-generate (admin) or identity/mfa/method/totp/<id>/generate (self) can mint a new TOTP secret and receive a QR-code-formatted URL. The implementation uses pquerna/otp/totp and stores the secret in the entity's MFA blob.

Integration points

• Auth methods: every login response can carry an MFARequirement.
• Identity store: TOTP secrets and method definitions are stored there.
• Audit: MFA attempts and validation results are audited just like normal logins.
• Login MFA does not mint a token; only Core.HandleRequest does, after successful validation.

Entry points for modification

• Add a new MFA provider: extend helper/identity/mfa/ with the configuration and validation, then add a path under vault/login_mfa.go.
• Tighten enforcement matching: see enforcementMatchAndEval in vault/login_mfa.go.
• Endpoint-level MFA (Enterprise feature stub): vault/login_mfa_ce.go.