or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

authentication.mdindex.mdkotlin-dsl.mdmethod-security.mdoauth2.mdreactive-web-security.mdsaml2.mdservlet-web-security.md
tile.json

servlet-web-security.mddocs/

Servlet Web Security

Core servlet-based web security configuration for Spring MVC applications using the HttpSecurity builder. Provides a fluent API for configuring authentication mechanisms, URL-based authorization, CSRF protection, CORS, session management, security headers, and custom security filters.

Capabilities

Enabling Web Security

Enable Spring Security for servlet-based applications using @EnableWebSecurity.

package org.springframework.security.config.annotation.web.configuration;

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@Documented
@Import({WebSecurityConfiguration.class, SpringWebMvcImportSelector.class,
         OAuth2ImportSelector.class, HttpSecurityConfiguration.class})
@EnableGlobalAuthentication
public @interface EnableWebSecurity {
    /**
     * Enable debug mode (prints detailed security filter chain information)
     */
    boolean debug() default false;
}

Usage:

@Configuration
@EnableWebSecurity
public class SecurityConfig {
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        // Configure security
        return http.build();
    }
}

HttpSecurity Builder

Main builder for configuring servlet-based web security. Injected as a parameter to SecurityFilterChain bean methods.

package org.springframework.security.config.annotation.web.builders;

public final class HttpSecurity extends
        AbstractConfiguredSecurityBuilder<DefaultSecurityFilterChain, HttpSecurity>
        implements SecurityBuilder<DefaultSecurityFilterChain>,
                   HttpSecurityBuilder<HttpSecurity> {

    // Authorization
    public HttpSecurity authorizeHttpRequests(
        Customizer<AuthorizeHttpRequestsConfigurer<HttpSecurity>.AuthorizationManagerRequestMatcherRegistry> customizer
    ) throws Exception;

    // Authentication Methods
    public HttpSecurity formLogin(
        Customizer<FormLoginConfigurer<HttpSecurity>> customizer
    ) throws Exception;

    public HttpSecurity httpBasic(
        Customizer<HttpBasicConfigurer<HttpSecurity>> customizer
    ) throws Exception;

    public HttpSecurity oauth2Login(
        Customizer<OAuth2LoginConfigurer<HttpSecurity>> customizer
    ) throws Exception;

    public HttpSecurity oauth2Client(
        Customizer<OAuth2ClientConfigurer<HttpSecurity>> customizer
    ) throws Exception;

    public HttpSecurity oauth2ResourceServer(
        Customizer<OAuth2ResourceServerConfigurer<HttpSecurity>> customizer
    ) throws Exception;

    public HttpSecurity oauth2AuthorizationServer(
        Customizer<OAuth2AuthorizationServerConfigurer> customizer
    ) throws Exception;

    public HttpSecurity saml2Login(
        Customizer<Saml2LoginConfigurer<HttpSecurity>> customizer
    ) throws Exception;

    public HttpSecurity saml2Logout(
        Customizer<Saml2LogoutConfigurer<HttpSecurity>> customizer
    ) throws Exception;

    public HttpSecurity saml2Metadata(
        Customizer<Saml2MetadataConfigurer<HttpSecurity>> customizer
    ) throws Exception;

    public HttpSecurity oidcLogout(
        Customizer<OidcLogoutConfigurer<HttpSecurity>> customizer
    ) throws Exception;

    public HttpSecurity oneTimeTokenLogin(
        Customizer<OneTimeTokenLoginConfigurer<HttpSecurity>> customizer
    ) throws Exception;

    public HttpSecurity rememberMe(
        Customizer<RememberMeConfigurer<HttpSecurity>> customizer
    ) throws Exception;

    public HttpSecurity x509(
        Customizer<X509Configurer<HttpSecurity>> customizer
    ) throws Exception;

    public HttpSecurity webAuthn(
        Customizer<WebAuthnConfigurer<HttpSecurity>> customizer
    ) throws Exception;

    public HttpSecurity jee(
        Customizer<JeeConfigurer<HttpSecurity>> customizer
    ) throws Exception;

    public HttpSecurity anonymous(
        Customizer<AnonymousConfigurer<HttpSecurity>> customizer
    ) throws Exception;

    // Security Features
    public HttpSecurity logout(
        Customizer<LogoutConfigurer<HttpSecurity>> customizer
    ) throws Exception;

    public HttpSecurity sessionManagement(
        Customizer<SessionManagementConfigurer<HttpSecurity>> customizer
    ) throws Exception;

    public HttpSecurity csrf(
        Customizer<CsrfConfigurer<HttpSecurity>> customizer
    ) throws Exception;

    public HttpSecurity cors(
        Customizer<CorsConfigurer<HttpSecurity>> customizer
    ) throws Exception;

    public HttpSecurity headers(
        Customizer<HeadersConfigurer<HttpSecurity>> customizer
    ) throws Exception;

    public HttpSecurity exceptionHandling(
        Customizer<ExceptionHandlingConfigurer<HttpSecurity>> customizer
    ) throws Exception;

    public HttpSecurity requestCache(
        Customizer<RequestCacheConfigurer<HttpSecurity>> customizer
    ) throws Exception;

    public HttpSecurity securityContext(
        Customizer<SecurityContextConfigurer<HttpSecurity>> customizer
    ) throws Exception;

    public HttpSecurity servletApi(
        Customizer<ServletApiConfigurer<HttpSecurity>> customizer
    ) throws Exception;

    public HttpSecurity portMapper(
        Customizer<PortMapperConfigurer<HttpSecurity>> customizer
    ) throws Exception;

    public HttpSecurity requiresChannel(
        Customizer<ChannelSecurityConfigurer<HttpSecurity>> customizer
    ) throws Exception;

    public HttpSecurity passwordManagement(
        Customizer<PasswordManagementConfigurer<HttpSecurity>> customizer
    ) throws Exception;

    // Custom Configuration
    public <C extends SecurityConfigurerAdapter<DefaultSecurityFilterChain, HttpSecurity>> C
        apply(C configurer) throws Exception;

    public <C extends AbstractHttpConfigurer<C, HttpSecurity>> HttpSecurity
        with(C configurer, Customizer<C> customizer) throws Exception;

    // Filter Management
    public HttpSecurity addFilter(Filter filter);

    public HttpSecurity addFilterBefore(Filter filter, Class<? extends Filter> beforeFilter);

    public HttpSecurity addFilterAfter(Filter filter, Class<? extends Filter> afterFilter);

    public HttpSecurity addFilterAt(Filter filter, Class<? extends Filter> atFilter);

    // Request Matching
    public HttpSecurity securityMatcher(String... patterns);

    public HttpSecurity securityMatcher(RequestMatcher... requestMatchers);

    public HttpSecurity securityMatchers(
        Customizer<RequestMatcherConfigurer> requestMatcherCustomizer
    );

    // Authentication Configuration
    public HttpSecurity authenticationManager(AuthenticationManager authenticationManager);

    public HttpSecurity authenticationProvider(AuthenticationProvider authenticationProvider);

    public HttpSecurity userDetailsService(UserDetailsService userDetailsService) throws Exception;

    // Build
    public DefaultSecurityFilterChain build() throws Exception;

    // Shared Objects
    public <C> C getSharedObject(Class<C> sharedType);

    public <C> void setSharedObject(Class<C> sharedType, C object);
}

URL-Based Authorization

Configure URL-based access control using authorizeHttpRequests().

package org.springframework.security.config.annotation.web.configurers;

public final class AuthorizeHttpRequestsConfigurer<H extends HttpSecurityBuilder<H>>
        extends AbstractHttpConfigurer<AuthorizeHttpRequestsConfigurer<H>, H> {

    public final class AuthorizationManagerRequestMatcherRegistry
            extends AbstractRequestMatcherRegistry<AuthorizedUrl> {

        // Request Matchers
        public AuthorizedUrl requestMatchers(String... patterns);

        public AuthorizedUrl requestMatchers(HttpMethod method, String... patterns);

        public AuthorizedUrl requestMatchers(RequestMatcher... requestMatchers);

        public AuthorizedUrl anyRequest();

        // Authorization Rules (on AuthorizedUrl)
        public AuthorizationManagerRequestMatcherRegistry permitAll();

        public AuthorizationManagerRequestMatcherRegistry denyAll();

        public AuthorizationManagerRequestMatcherRegistry authenticated();

        public AuthorizationManagerRequestMatcherRegistry anonymous();

        public AuthorizationManagerRequestMatcherRegistry rememberMe();

        public AuthorizationManagerRequestMatcherRegistry fullyAuthenticated();

        public AuthorizationManagerRequestMatcherRegistry hasRole(String role);

        public AuthorizationManagerRequestMatcherRegistry hasAnyRole(String... roles);

        public AuthorizationManagerRequestMatcherRegistry hasAuthority(String authority);

        public AuthorizationManagerRequestMatcherRegistry hasAnyAuthority(String... authorities);

        public AuthorizationManagerRequestMatcherRegistry hasIpAddress(String ipAddressExpression);

        public AuthorizationManagerRequestMatcherRegistry access(
            AuthorizationManager<RequestAuthorizationContext> manager
        );
    }
}

Usage Examples:

http
    .authorizeHttpRequests(authorize -> authorize
        // Public resources
        .requestMatchers("/", "/home", "/public/**").permitAll()

        // Role-based access
        .requestMatchers("/admin/**").hasRole("ADMIN")
        .requestMatchers("/user/**").hasAnyRole("USER", "ADMIN")

        // Authority-based access
        .requestMatchers("/api/read/**").hasAuthority("READ_PRIVILEGE")
        .requestMatchers("/api/write/**").hasAnyAuthority("WRITE_PRIVILEGE", "ADMIN_PRIVILEGE")

        // HTTP method-specific
        .requestMatchers(HttpMethod.GET, "/api/**").hasAuthority("READ")
        .requestMatchers(HttpMethod.POST, "/api/**").hasAuthority("WRITE")
        .requestMatchers(HttpMethod.DELETE, "/api/**").hasRole("ADMIN")

        // IP-based access
        .requestMatchers("/internal/**").hasIpAddress("192.168.1.0/24")

        // Custom authorization manager
        .requestMatchers("/custom/**").access(new CustomAuthorizationManager())

        // Default: require authentication for everything else
        .anyRequest().authenticated()
    );

Form Login

Configure form-based authentication.

package org.springframework.security.config.annotation.web.configurers;

public final class FormLoginConfigurer<H extends HttpSecurityBuilder<H>>
        extends AbstractAuthenticationFilterConfigurer<H, FormLoginConfigurer<H>,
                                                       UsernamePasswordAuthenticationFilter> {

    public FormLoginConfigurer<H> loginPage(String loginPage);

    public FormLoginConfigurer<H> loginProcessingUrl(String loginProcessingUrl);

    public FormLoginConfigurer<H> usernameParameter(String usernameParameter);

    public FormLoginConfigurer<H> passwordParameter(String passwordParameter);

    public FormLoginConfigurer<H> failureUrl(String authenticationFailureUrl);

    public FormLoginConfigurer<H> defaultSuccessUrl(String defaultSuccessUrl);

    public FormLoginConfigurer<H> defaultSuccessUrl(String defaultSuccessUrl, boolean alwaysUse);

    public FormLoginConfigurer<H> successHandler(
        AuthenticationSuccessHandler successHandler
    );

    public FormLoginConfigurer<H> failureHandler(
        AuthenticationFailureHandler failureHandler
    );

    public FormLoginConfigurer<H> failureForwardUrl(String forwardUrl);

    public FormLoginConfigurer<H> successForwardUrl(String forwardUrl);

    public FormLoginConfigurer<H> authenticationDetailsSource(
        AuthenticationDetailsSource<HttpServletRequest, ?> authenticationDetailsSource
    );

    public FormLoginConfigurer<H> permitAll();

    public FormLoginConfigurer<H> permitAll(boolean permitAll);
}

Usage Examples:

// Default form login
http.formLogin(Customizer.withDefaults());

// Custom form login
http.formLogin(form -> form
    .loginPage("/login")
    .loginProcessingUrl("/perform-login")
    .usernameParameter("email")
    .passwordParameter("pwd")
    .defaultSuccessUrl("/dashboard", true)
    .failureUrl("/login?error=true")
    .permitAll()
);

// With custom handlers
http.formLogin(form -> form
    .successHandler((request, response, authentication) -> {
        response.sendRedirect("/welcome");
    })
    .failureHandler((request, response, exception) -> {
        response.sendRedirect("/login?error=" + exception.getMessage());
    })
);

HTTP Basic Authentication

Configure HTTP Basic authentication.

package org.springframework.security.config.annotation.web.configurers;

public final class HttpBasicConfigurer<B extends HttpSecurityBuilder<B>>
        extends AbstractHttpConfigurer<HttpBasicConfigurer<B>, B> {

    public HttpBasicConfigurer<B> realmName(String realmName);

    public HttpBasicConfigurer<B> authenticationEntryPoint(
        AuthenticationEntryPoint authenticationEntryPoint
    );

    public HttpBasicConfigurer<B> authenticationDetailsSource(
        AuthenticationDetailsSource<HttpServletRequest, ?> authenticationDetailsSource
    );

    public HttpBasicConfigurer<B> authenticationConverter(
        AuthenticationConverter authenticationConverter
    );
}

Usage Examples:

// Default HTTP Basic
http.httpBasic(Customizer.withDefaults());

// Custom realm
http.httpBasic(basic -> basic
    .realmName("My Application")
);

// Custom entry point
http.httpBasic(basic -> basic
    .authenticationEntryPoint((request, response, authException) -> {
        response.addHeader("WWW-Authenticate", "Basic realm=\"My Realm\"");
        response.sendError(HttpServletResponse.SC_UNAUTHORIZED);
    })
);

CSRF Protection

Configure Cross-Site Request Forgery (CSRF) protection.

package org.springframework.security.config.annotation.web.configurers;

public final class CsrfConfigurer<H extends HttpSecurityBuilder<H>>
        extends AbstractHttpConfigurer<CsrfConfigurer<H>, H> {

    public CsrfConfigurer<H> csrfTokenRepository(CsrfTokenRepository csrfTokenRepository);

    public CsrfConfigurer<H> csrfTokenRequestHandler(
        CsrfTokenRequestHandler requestHandler
    );

    public CsrfConfigurer<H> requireCsrfProtectionMatcher(
        RequestMatcher requireCsrfProtectionMatcher
    );

    public CsrfConfigurer<H> sessionAuthenticationStrategy(
        SessionAuthenticationStrategy sessionAuthenticationStrategy
    );

    public CsrfConfigurer<H> ignoringRequestMatchers(RequestMatcher... requestMatchers);

    public CsrfConfigurer<H> ignoringRequestMatchers(String... patterns);
}

Usage Examples:

// Enable CSRF (enabled by default)
http.csrf(Customizer.withDefaults());

// Disable CSRF (for stateless APIs)
http.csrf(csrf -> csrf.disable());

// CSRF with cookie repository (for SPA/JavaScript clients)
http.csrf(csrf -> csrf
    .csrfTokenRepository(CookieCsrfTokenRepository.withHttpOnlyFalse())
);

// Ignore CSRF for specific endpoints
http.csrf(csrf -> csrf
    .ignoringRequestMatchers("/api/public/**", "/webhook/**")
);

CORS Configuration

Configure Cross-Origin Resource Sharing (CORS).

package org.springframework.security.config.annotation.web.configurers;

public final class CorsConfigurer<H extends HttpSecurityBuilder<H>>
        extends AbstractHttpConfigurer<CorsConfigurer<H>, H> {

    public CorsConfigurer<H> configurationSource(
        CorsConfigurationSource configurationSource
    );
}

Usage Examples:

import org.springframework.web.cors.CorsConfiguration;
import org.springframework.web.cors.CorsConfigurationSource;
import org.springframework.web.cors.UrlBasedCorsConfigurationSource;

// Use CORS configuration from @CrossOrigin annotations
http.cors(Customizer.withDefaults());

// Custom CORS configuration
http.cors(cors -> cors
    .configurationSource(request -> {
        CorsConfiguration config = new CorsConfiguration();
        config.setAllowedOrigins(List.of("https://example.com"));
        config.setAllowedMethods(List.of("GET", "POST", "PUT", "DELETE"));
        config.setAllowedHeaders(List.of("*"));
        config.setAllowCredentials(true);
        return config;
    })
);

// Using a bean
@Bean
public CorsConfigurationSource corsConfigurationSource() {
    CorsConfiguration configuration = new CorsConfiguration();
    configuration.setAllowedOrigins(List.of("https://example.com"));
    configuration.setAllowedMethods(List.of("*"));
    UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
    source.registerCorsConfiguration("/**", configuration);
    return source;
}

Session Management

Configure session creation, fixation protection, and concurrent session control.

package org.springframework.security.config.annotation.web.configurers;

public final class SessionManagementConfigurer<H extends HttpSecurityBuilder<H>>
        extends AbstractHttpConfigurer<SessionManagementConfigurer<H>, H> {

    public SessionManagementConfigurer<H> sessionCreationPolicy(
        SessionCreationPolicy sessionCreationPolicy
    );

    public SessionFixationConfigurer sessionFixation();

    public ConcurrencyControlConfigurer maximumSessions(int maximumSessions);

    public SessionManagementConfigurer<H> sessionConcurrency(
        Customizer<ConcurrencyControlConfigurer> concurrencyControlCustomizer
    );

    public SessionManagementConfigurer<H> invalidSessionUrl(String invalidSessionUrl);

    public SessionManagementConfigurer<H> invalidSessionStrategy(
        InvalidSessionStrategy invalidSessionStrategy
    );

    public SessionManagementConfigurer<H> sessionAuthenticationErrorUrl(
        String sessionAuthenticationErrorUrl
    );

    public SessionManagementConfigurer<H> sessionAuthenticationFailureHandler(
        AuthenticationFailureHandler failureHandler
    );

    public SessionManagementConfigurer<H> sessionAuthenticationStrategy(
        SessionAuthenticationStrategy sessionAuthenticationStrategy
    );

    public SessionManagementConfigurer<H> enableSessionUrlRewriting(
        boolean enableSessionUrlRewriting
    );

    // Session Fixation Configurer
    public final class SessionFixationConfigurer {
        public SessionManagementConfigurer<H> newSession();
        public SessionManagementConfigurer<H> migrateSession();
        public SessionManagementConfigurer<H> changeSessionId();
        public SessionManagementConfigurer<H> none();
    }

    // Concurrency Control Configurer
    public final class ConcurrencyControlConfigurer {
        public ConcurrencyControlConfigurer maxSessionsPreventsLogin(boolean maxSessionsPreventsLogin);
        public ConcurrencyControlConfigurer expiredUrl(String expiredUrl);
        public ConcurrencyControlConfigurer expiredSessionStrategy(SessionInformationExpiredStrategy expiredSessionStrategy);
        public ConcurrencyControlConfigurer sessionRegistry(SessionRegistry sessionRegistry);
    }
}

Usage Examples:

// Stateless session (for REST APIs)
http.sessionManagement(session -> session
    .sessionCreationPolicy(SessionCreationPolicy.STATELESS)
);

// Session fixation protection
http.sessionManagement(session -> session
    .sessionFixation().changeSessionId() // Default in Spring Security
);

// Concurrent session control
http.sessionManagement(session -> session
    .maximumSessions(1)
    .maxSessionsPreventsLogin(true) // Prevent new login if max reached
    .expiredUrl("/session-expired")
);

// Custom session strategy
http.sessionManagement(session -> session
    .sessionCreationPolicy(SessionCreationPolicy.IF_REQUIRED)
    .invalidSessionUrl("/invalid-session")
    .sessionAuthenticationStrategy(new CompositeSessionAuthenticationStrategy(
        List.of(
            new ChangeSessionIdAuthenticationStrategy(),
            new CsrfAuthenticationStrategy(new HttpSessionCsrfTokenRepository())
        )
    ))
);

Security Headers

Configure security-related HTTP response headers.

package org.springframework.security.config.annotation.web.configurers;

public final class HeadersConfigurer<H extends HttpSecurityBuilder<H>>
        extends AbstractHttpConfigurer<HeadersConfigurer<H>, H> {

    public CacheControlConfig cacheControl();

    public CacheControlConfig cacheControl(Customizer<CacheControlConfig> customizer);

    public ContentSecurityPolicyConfig contentSecurityPolicy(String policyDirectives);

    public ContentSecurityPolicyConfig contentSecurityPolicy(
        Customizer<ContentSecurityPolicyConfig> customizer
    );

    public ContentTypeOptionsConfig contentTypeOptions();

    public FrameOptionsConfig frameOptions();

    public FrameOptionsConfig frameOptions(Customizer<FrameOptionsConfig> customizer);

    public HstsConfig httpStrictTransportSecurity();

    public HstsConfig httpStrictTransportSecurity(Customizer<HstsConfig> customizer);

    public HpkpConfig httpPublicKeyPinning();

    public XXssConfig xssProtection();

    public XXssConfig xssProtection(Customizer<XXssConfig> customizer);

    public ReferrerPolicyConfig referrerPolicy();

    public ReferrerPolicyConfig referrerPolicy(Customizer<ReferrerPolicyConfig> customizer);

    public PermissionsPolicyConfig permissionsPolicy();

    public PermissionsPolicyConfig permissionsPolicy(Customizer<PermissionsPolicyConfig> customizer);

    public CrossOriginEmbedderPolicyConfig crossOriginEmbedderPolicy();

    public CrossOriginOpenerPolicyConfig crossOriginOpenerPolicy();

    public CrossOriginResourcePolicyConfig crossOriginResourcePolicy();

    public HeadersConfigurer<H> defaultsDisabled();

    public HeadersConfigurer<H> addHeaderWriter(HeaderWriter headerWriter);
}

Usage Examples:

// Default security headers
http.headers(Customizer.withDefaults());

// Custom Content Security Policy
http.headers(headers -> headers
    .contentSecurityPolicy(csp -> csp
        .policyDirectives("default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'")
    )
);

// Frame Options
http.headers(headers -> headers
    .frameOptions(frame -> frame
        .sameOrigin() // Allow framing from same origin
        // .deny() - Deny all framing
    )
);

// HTTP Strict Transport Security (HSTS)
http.headers(headers -> headers
    .httpStrictTransportSecurity(hsts -> hsts
        .includeSubDomains(true)
        .maxAgeInSeconds(31536000) // 1 year
    )
);

// Disable specific headers
http.headers(headers -> headers
    .defaultsDisabled()
    .cacheControl(Customizer.withDefaults())
    .frameOptions(Customizer.withDefaults())
);

// Cross-Origin Policies (for enhanced security)
http.headers(headers -> headers
    .crossOriginEmbedderPolicy(coep -> coep
        .policy(CrossOriginEmbedderPolicyHeaderWriter.CrossOriginEmbedderPolicy.REQUIRE_CORP)
    )
    .crossOriginOpenerPolicy(coop -> coop
        .policy(CrossOriginOpenerPolicyHeaderWriter.CrossOriginOpenerPolicy.SAME_ORIGIN)
    )
    .crossOriginResourcePolicy(corp -> corp
        .policy(CrossOriginResourcePolicyHeaderWriter.CrossOriginResourcePolicy.SAME_ORIGIN)
    )
);

// Permissions Policy (formerly Feature Policy)
http.headers(headers -> headers
    .permissionsPolicy(permissions -> permissions
        .policy("geolocation=(self), microphone=()")
    )
);

Logout Configuration

Configure logout behavior.

package org.springframework.security.config.annotation.web.configurers;

public final class LogoutConfigurer<H extends HttpSecurityBuilder<H>>
        extends AbstractHttpConfigurer<LogoutConfigurer<H>, H> {

    public LogoutConfigurer<H> logoutUrl(String logoutUrl);

    public LogoutConfigurer<H> logoutRequestMatcher(RequestMatcher logoutRequestMatcher);

    public LogoutConfigurer<H> logoutSuccessUrl(String logoutSuccessUrl);

    public LogoutConfigurer<H> logoutSuccessHandler(LogoutSuccessHandler logoutSuccessHandler);

    public LogoutConfigurer<H> invalidateHttpSession(boolean invalidateHttpSession);

    public LogoutConfigurer<H> deleteCookies(String... cookieNamesToClear);

    public LogoutConfigurer<H> clearAuthentication(boolean clearAuthentication);

    public LogoutConfigurer<H> addLogoutHandler(LogoutHandler logoutHandler);

    public LogoutConfigurer<H> permitAll();

    public LogoutConfigurer<H> permitAll(boolean permitAll);

    public LogoutConfigurer<H> defaultLogoutSuccessHandlerFor(
        LogoutSuccessHandler handler,
        RequestMatcher preferredMatcher
    );
}

Usage Examples:

// Default logout
http.logout(Customizer.withDefaults());

// Custom logout
http.logout(logout -> logout
    .logoutUrl("/perform-logout")
    .logoutSuccessUrl("/")
    .invalidateHttpSession(true)
    .deleteCookies("JSESSIONID", "remember-me")
    .clearAuthentication(true)
    .permitAll()
);

// Custom logout handler
http.logout(logout -> logout
    .addLogoutHandler((request, response, authentication) -> {
        // Custom cleanup logic
        auditService.logLogout(authentication.getName());
    })
    .logoutSuccessHandler((request, response, authentication) -> {
        response.sendRedirect("/goodbye");
    })
);

Exception Handling

Configure authentication entry points and access denied handlers.

package org.springframework.security.config.annotation.web.configurers;

public final class ExceptionHandlingConfigurer<H extends HttpSecurityBuilder<H>>
        extends AbstractHttpConfigurer<ExceptionHandlingConfigurer<H>, H> {

    public ExceptionHandlingConfigurer<H> authenticationEntryPoint(
        AuthenticationEntryPoint authenticationEntryPoint
    );

    public ExceptionHandlingConfigurer<H> accessDeniedPage(String accessDeniedUrl);

    public ExceptionHandlingConfigurer<H> accessDeniedHandler(
        AccessDeniedHandler accessDeniedHandler
    );

    public ExceptionHandlingConfigurer<H> defaultAuthenticationEntryPointFor(
        AuthenticationEntryPoint entryPoint,
        RequestMatcher preferredMatcher
    );

    public ExceptionHandlingConfigurer<H> defaultAccessDeniedHandlerFor(
        AccessDeniedHandler deniedHandler,
        RequestMatcher preferredMatcher
    );
}

Usage Examples:

// Custom exception handling
http.exceptionHandling(exceptions -> exceptions
    .authenticationEntryPoint((request, response, authException) -> {
        response.sendError(HttpServletResponse.SC_UNAUTHORIZED, "Unauthorized");
    })
    .accessDeniedHandler((request, response, accessDeniedException) -> {
        response.sendError(HttpServletResponse.SC_FORBIDDEN, "Access Denied");
    })
);

// Different handlers for different request types
http.exceptionHandling(exceptions -> exceptions
    .defaultAuthenticationEntryPointFor(
        new LoginUrlAuthenticationEntryPoint("/login"),
        new AntPathRequestMatcher("/app/**")
    )
    .defaultAuthenticationEntryPointFor(
        new HttpStatusEntryPoint(HttpStatus.UNAUTHORIZED),
        new AntPathRequestMatcher("/api/**")
    )
);

Custom Filters

Add custom security filters to the filter chain.

Usage Examples:

// Add custom filter
http.addFilter(new CustomAuthenticationFilter());

// Add filter before specific filter
http.addFilterBefore(new CustomPreAuthFilter(), UsernamePasswordAuthenticationFilter.class);

// Add filter after specific filter
http.addFilterAfter(new CustomPostAuthFilter(), BasicAuthenticationFilter.class);

// Add filter at specific position
http.addFilterAt(new CustomFilter(), UsernamePasswordAuthenticationFilter.class);

Request Matcher Configuration

Configure which requests the security filter chain applies to.

Usage Examples:

// Match specific patterns
http
    .securityMatcher("/api/**")
    .authorizeHttpRequests(authorize -> authorize
        .anyRequest().authenticated()
    );

// Multiple patterns
http
    .securityMatcher("/api/**", "/admin/**")
    .authorizeHttpRequests(authorize -> authorize
        .anyRequest().hasRole("ADMIN")
    );

// Custom request matcher
http
    .securityMatcher(new AntPathRequestMatcher("/secure/**"))
    .authorizeHttpRequests(authorize -> authorize
        .anyRequest().authenticated()
    );

WebSecurity Customization

Customize global web security settings, typically for ignoring certain requests.

package org.springframework.security.config.annotation.web.configuration;

@FunctionalInterface
public interface WebSecurityCustomizer {
    void customize(WebSecurity web);
}

Usage Example:

@Bean
public WebSecurityCustomizer webSecurityCustomizer() {
    return (web) -> web.ignoring()
        .requestMatchers("/resources/**", "/static/**", "/css/**", "/js/**", "/images/**");
}

Additional Configuration Options

Remember-Me Authentication

package org.springframework.security.config.annotation.web.configurers;

public final class RememberMeConfigurer<H extends HttpSecurityBuilder<H>>
        extends AbstractHttpConfigurer<RememberMeConfigurer<H>, H> {

    public RememberMeConfigurer<H> key(String key);

    public RememberMeConfigurer<H> tokenRepository(PersistentTokenRepository tokenRepository);

    public RememberMeConfigurer<H> userDetailsService(UserDetailsService userDetailsService);

    public RememberMeConfigurer<H> tokenValiditySeconds(int tokenValiditySeconds);

    public RememberMeConfigurer<H> useSecureCookie(boolean useSecureCookie);

    public RememberMeConfigurer<H> rememberMeParameter(String rememberMeParameter);

    public RememberMeConfigurer<H> rememberMeCookieName(String rememberMeCookieName);

    public RememberMeConfigurer<H> rememberMeCookieDomain(String rememberMeCookieDomain);

    public RememberMeConfigurer<H> rememberMeServices(RememberMeServices rememberMeServices);

    public RememberMeConfigurer<H> authenticationSuccessHandler(
        AuthenticationSuccessHandler authenticationSuccessHandler
    );

    public RememberMeConfigurer<H> alwaysRemember(boolean alwaysRemember);
}

X.509 Authentication

package org.springframework.security.config.annotation.web.configurers;

public final class X509Configurer<H extends HttpSecurityBuilder<H>>
        extends AbstractHttpConfigurer<X509Configurer<H>, H> {

    public X509Configurer<H> subjectPrincipalRegex(String subjectPrincipalRegex);

    public X509Configurer<H> x509PrincipalExtractor(X509PrincipalExtractor principalExtractor);

    public X509Configurer<H> authenticationUserDetailsService(
        AuthenticationUserDetailsService<X509AuthenticationToken> authenticationUserDetailsService
    );

    public X509Configurer<H> x509AuthenticationFilter(X509AuthenticationFilter x509AuthenticationFilter);

    public X509Configurer<H> authenticationDetailsSource(
        AuthenticationDetailsSource<HttpServletRequest, ?> authenticationDetailsSource
    );
}

One-Time Token Login

Passwordless authentication using single-use tokens delivered out-of-band (e.g., via email or SMS).

package org.springframework.security.config.annotation.web.configurers.ott;

public final class OneTimeTokenLoginConfigurer<H extends HttpSecurityBuilder<H>>
        extends AbstractAuthenticationFilterConfigurer<H, OneTimeTokenLoginConfigurer<H>, OneTimeTokenAuthenticationFilter> {

    public OneTimeTokenLoginConfigurer<H> tokenService(OneTimeTokenService oneTimeTokenService);

    public OneTimeTokenLoginConfigurer<H> authenticationConverter(AuthenticationConverter authenticationConverter);

    public OneTimeTokenLoginConfigurer<H> tokenGenerationSuccessHandler(
        OneTimeTokenGenerationSuccessHandler successHandler
    );

    public OneTimeTokenLoginConfigurer<H> generateTokenUrl(String generateTokenUrl);

    public OneTimeTokenLoginConfigurer<H> defaultSubmitPageUrl(String defaultSubmitPageUrl);

    public OneTimeTokenLoginConfigurer<H> showDefaultSubmitPage(boolean showDefaultSubmitPage);
}

Usage Example:

import org.springframework.security.authentication.ott.OneTimeTokenService;
import org.springframework.security.web.authentication.ott.OneTimeTokenGenerationSuccessHandler;

http
    .oneTimeTokenLogin(ott -> ott
        .generateTokenUrl("/ott/generate")
        .tokenGenerationSuccessHandler((request, response, oneTimeToken) -> {
            // Send token via email, SMS, etc.
            String token = oneTimeToken.getTokenValue();
            sendTokenByEmail(request.getParameter("username"), token);
        })
    );

Types:

  • OneTimeTokenService - Service for generating and consuming tokens
  • OneTimeTokenGenerationSuccessHandler - Handler invoked after token generation
  • GenerateOneTimeTokenRequest - Request for token generation
  • OneTimeToken - The generated token with expiration

Port Mapper

package org.springframework.security.config.annotation.web.configurers;

public final class PortMapperConfigurer<H extends HttpSecurityBuilder<H>>
        extends AbstractHttpConfigurer<PortMapperConfigurer<H>, H> {

    public PortMappings http(int httpPort);

    public final class PortMappings {
        public PortMapperConfigurer<H> mapsTo(int httpsPort);
    }
}

Channel Security

package org.springframework.security.config.annotation.web.configurers;

public final class ChannelSecurityConfigurer<H extends HttpSecurityBuilder<H>>
        extends AbstractHttpConfigurer<ChannelSecurityConfigurer<H>, H> {

    public ChannelSecurityConfigurer<H> channelProcessors(
        List<ChannelProcessor> channelProcessors
    );

    public ChannelRequestMatcherRegistry getRegistry();

    public final class ChannelRequestMatcherRegistry
            extends AbstractRequestMatcherRegistry<RequiresChannelUrl> {

        public MvcMatchersRequiresChannelUrl mvcMatchers(HttpMethod method, String... patterns);

        public MvcMatchersRequiresChannelUrl mvcMatchers(String... patterns);

        public RequiresChannelUrl requestMatchers(RequestMatcher... requestMatchers);

        public RequiresChannelUrl requestMatchers(String... patterns);

        public RequiresChannelUrl anyRequest();
    }
}

Types

// Session Creation Policy
public enum SessionCreationPolicy {
    ALWAYS,        // Always create an HttpSession
    NEVER,         // Never create an HttpSession, but use one if it exists
    IF_REQUIRED,   // Create an HttpSession only if required (default)
    STATELESS      // Never create an HttpSession and never use one
}

// HTTP Method
public enum HttpMethod {
    GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS, TRACE
}