Authentication

Overview

Contexa Identity provides four authentication methods. Each method creates an independent SecurityFilterChain, and priority is controlled via order().

All authentication methods support access to the full Spring Security API via rawHttp(), and support common options (order, CSRF, CORS, headers, logout, etc.).

Form Login

Traditional web form-based login. Configures Spring Security's formLogin() via the DSL. Default order is 100.

All Options

Basic Configuration

registry
    .form(form -> form
        .loginPage("/login")
        .defaultSuccessUrl("/home")
        .failureUrl("/login?error")
        .permitAll()
    )
    .session(Customizer.withDefaults())
    .build();

Custom Handlers

registry
    .form(form -> form
        .loginPage("/login")
        .usernameParameter("email")
        .passwordParameter("passwd")
        .successHandler(customSuccessHandler)
        .failureHandler(customFailureHandler)
    )
    .session(Customizer.withDefaults())
    .build();

Advanced Configuration (rawHttp + rawFormLogin)

registry
    .form(form -> form
        .order(20)
        .loginPage("/admin/login")
        .rawFormLogin(formLogin -> formLogin
            .usernameParameter("admin_user")
            .passwordParameter("admin_pass"))
        .rawHttp(http -> http
            .securityMatcher("/admin/**")
            .sessionManagement(session -> session
                .maximumSessions(1)
                .maxSessionsPreventsLogin(true)))
    )
    .session(Customizer.withDefaults())
    .build();

REST API Authentication

JSON-based REST API authentication. Authenticates via JSON payloads from frontend clients such as SPAs and mobile apps. Default order is 200.

All Options

Basic Configuration

registry
    .rest(rest -> rest
        .loginProcessingUrl("/api/auth/login")
    )
    .oauth2(Customizer.withDefaults())
    .build();

Stateless API Configuration (rawHttp)

registry
    .rest(rest -> rest
        .order(50)
        .loginProcessingUrl("/api/auth")
        .rawHttp(http -> http
            .securityMatcher("/api/**")
            .sessionManagement(session ->
                session.sessionCreationPolicy(SessionCreationPolicy.STATELESS)))
    )
    .oauth2(Customizer.withDefaults())
    .build();

One-Time Token (Magic Link)

Authentication via a one-time token sent by email or SMS. Passwordless authentication using the Magic Link approach. Default order is 300.

All Options

Basic Configuration

registry
    .ott(ott -> ott
        .tokenService(customTokenService)
        .tokenGenerationSuccessHandler(emailSendingHandler)
    )
    .session(Customizer.withDefaults())
    .build();

Custom Pages + Email Delivery Handler

registry
    .ott(ott -> ott
        .tokenGeneratingUrl("/auth/magic-link/request")
        .defaultSubmitPageUrl("/auth/magic-link/verify")
        // The public OTT DSL keeps the default token parameter name: "token"
        .showDefaultSubmitPage(false)
        .tokenService(jpaOneTimeTokenService)
        .tokenGenerationSuccessHandler((request, response, token) -> {
            String email = request.getParameter("username");
            emailService.sendMagicLink(email, token.getTokenValue());
            response.sendRedirect("/auth/magic-link/sent");
        })
    )
    .session(Customizer.withDefaults())
    .build();

WebAuthn / Passkey

FIDO2 WebAuthn-based biometric and hardware security key authentication. The most secure form of passwordless authentication. Default order is 400.

All Options

Basic Configuration

registry
    .passkey(passkey -> passkey
        .rpName("My Application")
        .rpId("example.com")
        .allowedOrigins("https://example.com")
    )
    .session(Customizer.withDefaults())
    .build();

Passkey Registration Flow

Passkey registration proceeds in three steps. The server stores credentials through Spring Security's UserCredentialRepository.

  Client                         Server
    |                               |
    |  1. POST /webauthn/register   |
    |        /options               |
    |  ---------------------------> |
    |                               | PublicKeyCredentialCreationOptions
    |  <--------------------------- | (rpId, rpName, userId, challenge)
    |                               |
    |  2. navigator.credentials     |
    |        .create(options)       |
    |  [Browser WebAuthn API]       |
    |                               |
    |  3. POST /webauthn/register   |
    |  ---------------------------> |
    |  (AuthenticatorAttestation    | Verify + Store in
    |   Response)                   | UserCredentialRepository
    |                               |
    |  <--- 201 Created ----------- |

Passkey Management REST API

Single Authentication vs MFA Second Factor

Passkey uses completely different URLs, adapters, and state management for single authentication versus MFA second-factor authentication.

Automatic Handler Resolution

When no custom handler is specified for an authentication method, the appropriate handler is automatically selected based on the authentication flow and state type.

Success / Failure Handler Selection Rules

SecurityContextRepository Selection Rules

For custom handler implementation, refer to the Extension Points section in the Adaptive MFA documentation.