State Management

Overview

Configure state by calling .session() or .oauth2() after an authentication method in the DSL. The AbstractFlowRegistrar.StateSetter applies the state to the most recently added flow.

registry
    .form(f -> f.loginPage("/login"))
    .session(Customizer.withDefaults())      // form -> Session

    .rest(r -> r.loginProcessingUrl("/api/auth"))
    .oauth2(Customizer.withDefaults())        // rest -> OAuth2

    .mfa(m -> m.primaryAuthentication(...).passkey(...))
    .session(Customizer.withDefaults())        // mfa -> Session

    .build();

Session vs OAuth2 Comparison

Session-Based

Configured via .session(Customizer.withDefaults()). Suitable for traditional web applications and server-side rendering.

Auto-Applied

• sessionFixation().changeSessionId() — Session fixation attack protection
• Session invalidation + cookie deletion on logout
• CompositeLogoutHandler integration (Strategy pattern)

Additional Configuration via rawHttp

.form(f -> f
    .rawHttp(http -> http.sessionManagement(s -> s
        .maximumSessions(1)
        .maxSessionsPreventsLogin(true)))
)
.session(Customizer.withDefaults())

OAuth2-Based

Configured via .oauth2(Customizer.withDefaults()). Suitable for SPA, microservices, and API servers.

Auto-Applied

• Resource Server: JWT authentication converter, authentication failure/access denied handlers, SessionCreationPolicy.STATELESS
• Authorization Server: AuthorizationService, ClientRepository, token endpoint, authenticated_user grant type, OIDC support
• OAuth2 CSRF: Controlled by the spring.auth.oauth2-csrf configuration

authenticated_user Grant Type

A custom grant type that issues OAuth2 tokens to users who have completed Identity authentication (Form, REST, MFA). It bridges traditional authentication with OAuth2 token issuance.

  authenticated_user Grant Flow
  ===============================

  [Form/REST/MFA Authentication Complete]
           |
           v
  [AuthenticatedUserGrantAuthenticationProvider]
           |
           +-- Client Verification
           +-- User Lookup (UserRepository)
           +-- Scope Resolution
           +-- Access Token Generation (JWT)
           +-- Refresh Token Generation (optional)
           +-- Authorization Persistence (transactional)
           |
           v
  [JWT Token Issuance Complete]

Configuration Properties

Core settings from AuthContextProperties (spring.auth.*).

Core Settings (spring.auth.*)

TokenTransportType Details

OAuth2 Settings (spring.auth.oauth2.*)

MFA Settings (spring.auth.mfa.*)

MFA Nested Settings

application.yml Example

spring:
  auth:
    state-type: OAUTH2
    token-transport-type: header_cookie
    access-token-validity: 3600000
    enable-refresh-token: true
    oauth2:
      client-id: my-client
      issuer-uri: https://auth.example.com
      jwk-key-store-path: classpath:keystore.jks
    mfa:
      session-timeout-ms: 600000
      otp-token-validity-seconds: 300
      session-storage-type: redis
      redis:
        key-prefix: mfa:session:
        cookie-name: MFA_SID