Adaptive MFA

Overview

Contexa MFA consists of primary authentication + secondary factor(s). The policy engine determines whether MFA is required, and the state machine manages the authentication flow.

The default MFA order is 200. Calling .form() or .rest() directly from .mfa() throws an UnsupportedOperationException. You must use .primaryAuthentication() instead.

Quick Start

The simplest MFA configuration with Form primary authentication + Passkey secondary authentication.

registry
    .mfa(mfa -> mfa
        .primaryAuthentication(primary -> primary
            .formLogin(form -> form.loginPage("/login")))
        .passkey(Customizer.withDefaults())
    )
    .session(Customizer.withDefaults())
    .build();

Primary Authentication

Configures the primary authentication method via primaryAuthentication(). Only one of formLogin() or restLogin() can be selected (mutually exclusive).

Form Primary

.mfa(mfa -> mfa
    .primaryAuthentication(primary -> primary
        .formLogin(form -> form
            .loginPage("/login")
            .usernameParameter("email")
            .failureUrl("/login?error")))
    .ott(Customizer.withDefaults())
)

REST Primary

.mfa(mfa -> mfa
    .primaryAuthentication(primary -> primary
        .restLogin(rest -> rest
            .loginProcessingUrl("/api/auth/login")))
    .passkey(Customizer.withDefaults())
)

MFA Factors (Secondary Authentication)

Adds secondary authentication factors. At least one secondary factor is required, and multiple factors can be combined.

Available Secondary Factors

Multiple Factor Combination

.mfa(mfa -> mfa
    .primaryAuthentication(primary -> primary
        .formLogin(form -> form.loginPage("/login")))
    .ott(ott -> ott
        .tokenService(emailTokenService))
    .passkey(passkey -> passkey
        .rpName("My App")
        .rpId("example.com"))
)

Each factor is automatically assigned a sequential order via currentStepOrderCounter (1, 2, 3...). Users select their preferred factor on the factor selection page.

requiredFactors() - Required Factor Count

Controls how many secondary factors must be completed for MFA to succeed. By default, all registered factors must be completed.

// Register 2 factors, but only 1 is required to complete MFA
.mfa(mfa -> mfa
    .primaryAuthentication(primary -> primary
        .formLogin(Customizer.withDefaults()))
    .passkey(Customizer.withDefaults())
    .ott(Customizer.withDefaults())
    .requiredFactors(1)
)

Use Case: Flexible Fallback

Register multiple factors for redundancy while requiring only one. Users who cannot use Passkey (e.g., no biometric hardware) can fall back to OTT email verification.

// Admin portal: Passkey preferred, OTT as fallback
.mfa(mfa -> mfa
    .urlPrefix("/admin")
    .primaryAuthentication(primary -> primary
        .formLogin(form -> form.defaultSuccessUrl("/admin")))
    .passkey(Customizer.withDefaults())   // Starts first (auto-selected)
    .ott(Customizer.withDefaults())       // Available as fallback
    .requiredFactors(1)                   // Only 1 needed
)

MFA Pages

Customizes the page URLs for each step of the MFA flow via mfaPage().

.mfa(mfa -> mfa
    .primaryAuthentication(primary -> primary
        .formLogin(form -> form.loginPage("/login")))
    .ott(Customizer.withDefaults())
    .mfaPage(page -> page
        .selectFactorPage("/mfa/select")
        .ottPages("/mfa/ott/request", "/mfa/ott/verify")
        .failurePageUrl("/mfa/failed"))
)

Creating Custom MFA Pages

You can freely modify the CSS and layout of MFA pages. However, the following elements must be preserved.

Do Not Modify

• CSRF meta tag: <meta name="_csrf" th:content="${csrfToken}">
• id="contexa-page-config" div and data-* attributes
• Input name attributes: username, password, token, _csrf, mfaSessionId
• Form id, method, th:action
• button id: loginButton, sendCodeButton, verifyButton, resendButton, authButton
• th:utext="${hiddenInputsHtml}" ??Auto-generates CSRF + mfaSessionId hidden inputs

Safe to Modify

• CSS colors, layout, background
• Logos, icons
• Text content
• Form field styles

Required JavaScript Files

MFA Data Flow

MFA Policy Customization

Implement MfaPolicyProvider to customize MFA requirement decisions. Since it is registered with @ConditionalOnMissingBean, defining a bean of the same type automatically overrides it.

Built-in Implementations

Custom Policy Implementation Example

@Bean
public MfaPolicyProvider mfaPolicyProvider() {
    return new MfaPolicyProvider() {
        @Override
        public MfaDecision evaluateInitialMfaRequirement(FactorContext ctx) {
            String ip = ctx.getRequest().getRemoteAddr();
            if (trustedIpRanges.contains(ip)) {
                return MfaDecision.noMfaRequired();
            }
            return MfaDecision.challenged("Untrusted IP");
        }
        // ... other methods
    };
}

MfaDecision Types

Injecting Policy via DSL

.mfa(mfa -> mfa
    .policyProvider(customMfaPolicyProvider)
    .primaryAuthentication(primary -> primary
        .formLogin(form -> form.loginPage("/login")))
    .passkey(Customizer.withDefaults())
)

Step-up Authentication

Requires additional authentication when an already authenticated user accesses sensitive resources.

The ContexaMFA SDK Global Interceptor automatically detects 401/403/423 responses from all HTTP requests and redirects to the MFA challenge. After authentication completes, the original request is automatically retried.

MFA State Machine Events

Use @EventListener to receive MFA state change events for implementing audit logs, notifications, and more.

Event Types

Terminal States

Audit Log Implementation Example

@EventListener
public void onMfaStateChange(MfaStateMachineEvents.StateChangeEvent event) {
    auditService.log(
        event.getUserId(),
        event.getFromState(),
        event.getToState()
    );
}

@EventListener
public void onMfaError(MfaStateMachineEvents.ErrorEvent event) {
    alertService.notify(
        event.getErrorType(),
        event.getMessage()
    );
}

Multi MFA

Run multiple independent MFA flows simultaneously. Each flow has its own SecurityFilterChain, secondary authentication factors, and URL namespace.

requiredFactors() — Multi-Factor Count

By default, MFA requires all configured secondary factors to complete. For example, if you configure both .ott() and .passkey(), the user must complete both before MFA succeeds. Use requiredFactors(int count) to override this and require fewer factors than configured.

// Default: both OTT and Passkey required (2 factors registered = 2 required)
registry
    .mfa(mfa -> mfa
        .primaryAuthentication(auth -> auth.formLogin(Customizer.withDefaults()))
        .ott(Customizer.withDefaults())
        .passkey(Customizer.withDefaults())
    ).session(Customizer.withDefaults())

// Override: require only 1 of the 2 configured factors
registry
    .mfa(mfa -> mfa
        .requiredFactors(1)
        .primaryAuthentication(auth -> auth.formLogin(Customizer.withDefaults()))
        .ott(Customizer.withDefaults())
        .passkey(Customizer.withDefaults())
    ).session(Customizer.withDefaults())

Basic Configuration

Registering multiple .mfa() calls automatically assigns unique typeNames.

registry
    .mfa(mfa -> mfa
        .primaryAuthentication(auth -> auth.formLogin(Customizer.withDefaults()))
        .passkey(Customizer.withDefaults())
        .order(60)
    ).session(Customizer.withDefaults())   // typeName = "mfa" (auto)

    .mfa(mfa -> mfa
        .primaryAuthentication(auth -> auth.formLogin(Customizer.withDefaults()))
        .ott(Customizer.withDefaults())
        .order(70)
    ).session(Customizer.withDefaults())   // typeName = "mfa_2" (auto)

    .build();

name() - Explicit Flow Naming

Use name() to assign a meaningful flow name instead of auto-numbering.

.mfa(mfa -> mfa
    .name("admin")     // typeName = "mfa_admin"
    .primaryAuthentication(auth -> auth.formLogin(Customizer.withDefaults()))
    .passkey(Customizer.withDefaults())
    .order(60)
).session(Customizer.withDefaults())

.mfa(mfa -> mfa
    .name("user")      // typeName = "mfa_user"
    .primaryAuthentication(auth -> auth.formLogin(Customizer.withDefaults()))
    .ott(Customizer.withDefaults())
    .order(70)
).session(Customizer.withDefaults())

urlPrefix() - URL Isolation

urlPrefix() automatically applies a prefix to all MFA URLs for the flow and auto-configures securityMatcher. This ensures each Multi MFA flow operates in its own URL namespace.

registry
    // Admin: Passkey MFA
    .mfa(mfa -> mfa
        .urlPrefix("/admin")
        .primaryAuthentication(auth -> auth.formLogin(Customizer.withDefaults()))
        .passkey(Customizer.withDefaults())
        .order(60)
    ).session(Customizer.withDefaults())

    // User: OTT MFA
    .mfa(mfa -> mfa
        .urlPrefix("/user")
        .primaryAuthentication(auth -> auth.formLogin(Customizer.withDefaults()))
        .ott(Customizer.withDefaults())
        .order(70)
    ).session(Customizer.withDefaults())

    .build();

URL transformation when urlPrefix("/admin") is set:

defaultLoginUrl() - Individual URL Override

Use this when you want to change individual URLs instead of applying urlPrefix(). Changes the auto-generated login form URL while maintaining Spring Security standard custom page behavior.

.mfa(mfa -> mfa
    .primaryAuthentication(auth -> auth.formLogin(form -> form
        .defaultLoginUrl("/admin/mfa/login")
        .defaultSuccessUrl("/admin/dashboard")))
    .passkey(Customizer.withDefaults())
    .order(60)
).session(Customizer.withDefaults())

Multi MFA DSL API Summary

Important Notes

MFA + Single Authentication Co-configuration

Register both MFA and single authentication together to apply different authentication levels to different request paths.

registry
    // Admin: Form + OAuth2 (Single Auth)
    .form(f -> f.order(20).loginPage("/admin/login")
        .rawHttp(http -> http.securityMatcher("/admin/**")))
    .oauth2(Customizer.withDefaults())

    // User: MFA (Form Primary + Passkey) + Session
    .mfa(m -> m.order(100)
        .primaryAuthentication(auth -> auth
            .formLogin(form -> form.loginPage("/login")))
        .passkey(Customizer.withDefaults()))
    .session(Customizer.withDefaults())

    .build();

Use order() to control filter chain priority, and rawHttp()'s securityMatcher() to determine which chain handles which requests. Different state management (session/oauth2) can be configured for each authentication method.

MFA Handlers

Custom handlers can be specified for MFA success and failure.

.mfa(mfa -> mfa
    .mfaSuccessHandler(customSuccessHandler)
    .mfaFailureHandler(customFailureHandler)
    .primaryAuthentication(primary -> primary
        .formLogin(form -> form.loginPage("/login")))
    .passkey(Customizer.withDefaults())
)

For handler interfaces and implementation guidance, refer to the handler auto-selection section in the Authentication documentation.

MFA REST API

Response Format

ContexaMFA JavaScript SDK

A JavaScript SDK (v2.1.0) that controls the MFA flow in the browser.

Quick Start

<script src="/en/js/contexa-mfa-sdk.js?v=1776136758910"></script>
<script>
const mfa = new ContexaMFA.Client({
    autoInit: true,
    tokenPersistence: 'localStorage'
});
mfa.loginForm('username', 'password')
    .then(result => { /* handle result */ });
</script>

Client API

Constructor Options

Global Interceptor

Automatically detects 401/403/423 responses from all fetch/XMLHttpRequest calls and redirects to the Step-up authentication page. After authentication completes, the original request is automatically retried.