Skip to main content
Version: 4.1

IDP MFA Flow Developer Notes

This document describes the IDP first-factor, MFA, required-MFA registration, and WebAuthn continuation paths as implemented by the frontend handlers. It is intended as a debugging aid for regressions where the browser is sent back to /login, /login/webauthn, or /mfa/*/register even though an OIDC/SAML flow should resume.

Configuration Inputs​

The runtime path is not determined by the current URL alone. The IDP client and session state must be considered together.

InputMeaningImportant effects
skip_consentOIDC client consent can be skipped.A successful login can resume directly to the OIDC callback path after token/code handling.
delayed_responseThe first-factor password result is hidden until after MFA.A wrong password still enters MFA if the account/factors can be resolved; the failure is revealed after the second factor.
require_mfaList of MFA methods that must be registered for this client or service provider.After authentication, the flow may be diverted to /mfa/<method>/register before OIDC/SAML resumes. It must not silently narrow the login challenge methods when supported_mfa is unset, and it does not mean the current login used one of those methods.
supported_mfaExplicit list of MFA methods the client allows during login/registration.Methods not supported by the client must not be offered. When unset, all registered methods remain eligible; require_mfa and required_mfa_level are evaluated separately.
mfa_policy.levelsGlobal or client/SP-local mapping from MFA method to assurance level.Defaults are recovery_codes=1, totp=2, and webauthn=3. Client/SP policy merges over the global policy.
required_mfa_levelMinimum MFA assurance level required for normal browser SSO response issuance.If unset or zero, compatibility behavior applies: any fresh MFA-backed browser session can satisfy ordinary SSO. If positive, the session must carry a fresh assurance level at or above this value or step-up is required.
OIDC flow stateAuthorization request, client id, redirect URI, scopes, PKCE, prompt.Stored only in a typed Redis OIDCFlow bound to the SessionAnchor; the browser carries only opaque selectors.
SAML flow stateRequest, RelayState, entity id.Stored only in a typed Redis SAMLFlow, with the same opaque continuation model as OIDC.
Device-code flow stateUser code/device code and pending verification state.Stored in the cookie-free device store and typed browser flow; WebAuthn completion may need to call device-code completion instead of returning a browser redirect.
Backend referenceEdge session reference to the authority-side backend result.Stored in the SessionAnchor and preserved for follow-up MFA/backend-data lookups in split edge/authority deployments.
MFA factor identityAccount whose second factor is being verified.Can differ from final subject for formatted Master-User logins.
Final subject identityAccount that receives the completed IDP session.Must be restored after MFA before OIDC/SAML claim materialization.

The canonical browser contract is described in Browser Session Contract Inventory. The browser cookie is an authenticated opaque envelope that selects one SessionAnchor; it never stores identity, protocol requests, backend affinity, MFA state, assurance, consent, claims, redirect targets, or WebAuthn ceremony data.

Authentication and identity lookups enter the common AuthApplicationService with an exact host-owned internal caller profile. The active generation admits those profiles and runs the common Decision Service checkpoints. OIDC/SAML/device records, delayed-response state, MFA and WebAuthn ceremonies, consent, and claim-release lifecycle remain domain-owned; adapters pass only the explicit operation, transport, client/SP, correlation, localization, requested-attribute, and existing backend-affinity facts needed for the current call.

The top-level policy configuration, caller admission, catalog, extensions, and routes are committed as one generation. No IdP path retains a second evaluator or fallback policy authority.

The contrib/identity-proxy-e2e profile has two relevant OIDC clients:

client_id: split-e2e-mfa
skip_consent: true
require_mfa: [totp, webauthn, recovery_codes]
supported_mfa: [totp, webauthn, recovery_codes]

client_id: split-e2e-mfa-delayed
skip_consent: true
delayed_response: true
require_mfa: [totp, webauthn, recovery_codes]
supported_mfa: [totp, webauthn, recovery_codes]

State Owners​

First-Factor And MFA Selection​

Important invariant: once MFA availability has been computed from the password step and authority backend state, the immediate MFA continuation should not make a contradictory required-MFA decision because the WebAuthn finish request has a different body shape.

OIDC Reentry With Existing Sessions​

OIDC relying parties may start a new authorization request immediately after a successful token and userinfo exchange while the browser still has an authenticated account session. This is a new Authorization-Code request, not a continuation of the completed one. The handler must therefore persist a fresh OIDC flow for the current request before consent, MFA assurance, required-MFA registration, or code issuance is evaluated.

Completing the previous OIDC request may remove temporary flow keys, but it must not make the next valid /oidc/authorize depend on the unauthenticated login start path. Direct /login access without an active IDP flow remains rejected.

SSO MFA Assurance Versus Step-Up​

Normal OIDC/SAML application SSO and sensitive self-service mutations use the same MFA proof, but they have different freshness boundaries.

Expected invariants:

  • A user who just completed WebAuthn for one OIDC client has a fresh MFA-backed SSO session. A second OIDC client such as Roundcube must not immediately force another MFA challenge only because its require_mfa list names different enrollment methods when no stronger required_mfa_level is configured.
  • When required_mfa_level is positive, the browser session must have a fresh assurance level at or above that value. Registration of a high-level method is necessary for enrollment policy, but it is not sufficient to satisfy the assurance gate unless the user has actually completed a method whose configured level reaches the gate.
  • supported_mfa controls which challenge methods can be offered. If it is not configured, the UI offers the registered methods available to the user.
  • require_mfa controls which factor registrations must exist before the client response is issued.
  • required_mfa_level controls the normal browser SSO assurance strength. The default policy maps recovery codes to level 1, TOTP to level 2, and WebAuthn to level 3; operators may override the mapping globally or per OIDC client/SAML service provider.
  • delayed_response only hides first-factor success or failure until after MFA; it does not change which methods are supported and does not create a separate client-specific MFA step-up by itself.
  • Self-service actions that mutate MFA/account state remain the boundary for explicit step-up freshness checks.

MFA Level Policy​

require_mfa, supported_mfa, and required_mfa_level are separate policy axes:

  • require_mfa is enrollment policy. It answers which factors must exist before a client or service provider can receive a successful response.
  • supported_mfa is challenge-offer policy. It answers which registered methods may be shown during login, registration, or step-up.
  • required_mfa_level is assurance policy. It answers how strong the current fresh browser-session MFA proof must be before normal OIDC/SAML SSO may continue.

The default assurance mapping is:

identity:
mfa_policy:
levels:
recovery_codes: 1
totp: 2
webauthn: 3

Client and service-provider overrides merge over the global policy:

identity:
oidc:
clients:
- client_id: security-admin
require_mfa: [webauthn]
required_mfa_level: 3

- client_id: equal-rank-app
required_mfa_level: 2
mfa_policy:
levels:
totp: 2
webauthn: 2

saml:
service_providers:
- entity_id: https://sp.example.com/metadata
require_mfa: [totp]
required_mfa_level: 2

If application A completes TOTP at level 2 and application B requires level 3, B must trigger a visible step-up even when the user has WebAuthn registered. If the operator configures TOTP and WebAuthn at the same level, the same level-2 TOTP proof may satisfy a level-2 application B.

Delayed Response​

delayed_response means MFA handlers must validate the stored first-factor result after the second factor succeeds. It does not mean required-MFA registration should run against a different identity or backend reference.

WebAuthn Login Finish​

WebAuthn login is special because the browser sends a JSON assertion to /login/webauthn/finish. That request body is consumed by WebAuthn validation. Internal follow-up lookups must not treat the same JSON body as a Nauthilus auth request.

Required invariant for this handler:

  • The core WebAuthn verifier may consume the request body.
  • Any later backend-data, cache-purge, or MFA-availability check must use an explicit internal lookup profile and typed input; it must not decode the WebAuthn JSON assertion as a structured auth request.
  • The SessionAnchor and typed enrollment state preserve proven availability for TOTP, WebAuthn, and recovery codes so require_mfa does not reinterpret a proven factor as missing after temporary operation state is cleaned.
  • The handler must not write a second response after an internal lookup already aborted the request.
  • The continuation redirect must be derived server-side from flow state; the browser must only follow a safe relative redirect returned by the server.

WebAuthn ceremony restart contract​

The active browser runtime stores each ceremony only as an anchor-indexed typed Redis record. The begin response gives JavaScript a high-entropy opaque ceremony handle, which the finish request returns as a local query parameter. That handle has no authority without the matching canonical envelope, live SessionAnchor, parent flow, identity, protocol, ceremony kind, expiry, and revision bindings. Neither nauthilus_secure_data nor the retired nauthilus_webauthn_ceremony cookie carries ceremony state; the canonical runtime rejects and purges the retired representation.

A finish operation atomically takes the bound record before verification, so replay, stale handles, and binding mismatches cannot reuse a challenge. A missing, malformed, expired, kind-mismatched, or binding-mismatched handle fails closed. The page may call the matching begin endpoint to create a fresh record, but it never retries the rejected assertion or attestation. Targeted ceremony cleanup preserves a still-valid parent OIDC or SAML flow and its server-side identity, allowing a safe fresh begin without accepting old ceremony state.

The canonical runtime has no legacy-cookie fallback and must be deployed by controlled replacement. Browser traffic must not alternate between binaries that disagree on the canonical envelope and typed ceremony contract.

Required-MFA Registration​

require_mfa is about factor enrollment, not about the current login method alone. A client can require all of totp, webauthn, and recovery_codes, so after a successful password or MFA step the flow must prove that every required method is already registered.

Required invariant for split edge/authority deployments:

  • The check must use the same final subject, factor identity, backend name, and backend reference that were selected during first-factor authentication.
  • Explicit supported_mfa is the configured allow-list. If it is unset, the challenge method set is not narrowed by require_mfa; normal SSO accepts any fresh MFA proof and the required-MFA registration check still follows require_mfa directly.
  • An internal lookup must use the exact application-service profile and preserve the canonical session handle, typed identity, protocol context, and existing backend affinity. It must not reconstruct them from browser input.
  • The anchor/enrollment availability snapshot may satisfy a method only when that method was already proven by backend lookup, registration, or a completed challenge; it must not invent factor enrollment state.
  • The MFA select page may merge previously proven anchor/enrollment state with fresh backend data so the UI does not hide a factor already observed in the same canonical session. The explicit supported_mfa allow-list is still applied after that merge.
  • A failed or incomplete lookup must fail closed for security, but it should be observable as a lookup failure, not silently downgraded to "factor missing" when the factor was proven earlier in the same flow.

Roundcube After Existing SSO​

Roundcube is a normal OIDC Authorization-Code client. If the browser already has a fresh MFA-backed SSO session from another client, for example after a WebAuthn login to Heimdal, Roundcube must not immediately force another MFA challenge only because its require_mfa list contains totp and recovery_codes. A Roundcube-like client that configures required_mfa_level must still satisfy that explicit level gate.

Important distinction:

  • Browser SSO uses sessionSatisfiesIDPSSOMFAAssurance, which accepts a fresh same-session MFA proof even when the proof came from a different OIDC client.
  • Device-code approval and self-service mutations keep stricter freshness gates.
  • Required registration is still enforced. Missing TOTP or recovery-code enrollment redirects to /mfa/<method>/register, not to /login/mfa.
  • The select page should offer every registered method allowed by supported_mfa. When supported_mfa is unset, it must not hide WebAuthn just because require_mfa lists TOTP and recovery codes.

Expected Required-MFA Flow For split-e2e-mfa​

If the last step redirects to /mfa/totp/register, the code has contradicted state it had already established earlier in the same test profile. The likely places to audit are:

  • loss of typed enrollment, backend-affinity, or identity fields during MFA cleanup or anchor transition;
  • using the WebAuthn JSON finish request as a structured auth request in an internal lookup;
  • using final subject identity where factor identity is required, or the reverse, especially for Master-User logins;
  • treating backend-data lookup failure as "factor missing" without logging the difference;
  • supported_mfa filtering that removes a registered method before the require_mfa comparison.

Regression tests should cover two separate outcomes:

  • A normal browser SSO request with a fresh WebAuthn proof from another client reaches the OIDC callback for Roundcube without visiting /login/mfa.
  • When a challenge is actually needed, the select page still contains every registered and supported method, including WebAuthn when supported_mfa is unset.

Code Map​

AreaCurrent files
Route registration and browser handlersserver/handler/frontend/idp/frontend.go and canonical_*.go
Required-MFA and step-up decisionsserver/handler/frontend/idp/canonical_mfa_selection.go and server/sessionstate/contracts.go
OIDC/SAML flow stateserver/idp/flow/ and server/sessionstate/
Authentication and identity boundaryserver/core/auth_application_service.go and server/core/authn_application_adapter.go
Backend-data/MFA lookup adapterserver/handler/frontend/idp/backend_data.go
WebAuthn ceremony and sign-count handlingserver/handler/frontend/idp/canonical_webauthn.go, server/core/canonical_webauthn_ceremony_store.go, and server/core/webauthn.go
Login completion and assuranceserver/core/cookie/login_completion.go and server/core/cookie/composition.go
Server-side identity and backend affinityserver/sessionstate/contracts.go and server/core/cookie/composition.go
Browser E2E profilecontrib/identity-proxy-e2e/scripts/browser-e2e.js
Split edge/authority configcontrib/identity-proxy-e2e/config/edge-a.yml and edge-b.yml