Spring Security configuration module providing comprehensive declarative security configuration capabilities for Spring applications
—
Spring Security Config provides specialized configurers for different aspects of HTTP security. These configurers work with HttpSecurity to provide fluent configuration APIs for authentication, authorization, and security protection features.
Configuration for form-based authentication with login pages and handlers.
public final class FormLoginConfigurer<H extends HttpSecurityBuilder<H>>
extends AbstractAuthenticationFilterConfigurer<H, FormLoginConfigurer<H>, UsernamePasswordAuthenticationFilter> {
// Login Page Configuration
public FormLoginConfigurer<H> loginPage(String loginPage);
public FormLoginConfigurer<H> loginProcessingUrl(String loginProcessingUrl);
// Success Handling
public FormLoginConfigurer<H> defaultSuccessUrl(String defaultSuccessUrl);
public FormLoginConfigurer<H> defaultSuccessUrl(String defaultSuccessUrl, boolean alwaysUse);
public FormLoginConfigurer<H> successForwardUrl(String forwardUrl);
public FormLoginConfigurer<H> successHandler(AuthenticationSuccessHandler successHandler);
// Failure Handling
public FormLoginConfigurer<H> failureUrl(String authenticationFailureUrl);
public FormLoginConfigurer<H> failureForwardUrl(String forwardUrl);
public FormLoginConfigurer<H> failureHandler(AuthenticationFailureHandler authenticationFailureHandler);
// Parameter Names
public FormLoginConfigurer<H> usernameParameter(String usernameParameter);
public FormLoginConfigurer<H> passwordParameter(String passwordParameter);
// Permission Configuration
public FormLoginConfigurer<H> permitAll();
public FormLoginConfigurer<H> permitAll(boolean permitAll);
}Usage Example:
http.formLogin(form -> form
.loginPage("/custom-login")
.loginProcessingUrl("/authenticate")
.usernameParameter("email")
.passwordParameter("password")
.defaultSuccessUrl("/dashboard", true)
.failureUrl("/login?error=true")
.successHandler((request, response, authentication) -> {
response.sendRedirect("/welcome");
})
.failureHandler((request, response, exception) -> {
request.setAttribute("error", exception.getMessage());
request.getRequestDispatcher("/login?error").forward(request, response);
})
.permitAll()
);Configuration for HTTP Basic authentication.
public final class HttpBasicConfigurer<H extends HttpSecurityBuilder<H>>
extends AbstractHttpConfigurer<HttpBasicConfigurer<H>, H> {
// Realm Configuration
public HttpBasicConfigurer<H> realmName(String realmName);
// Authentication Entry Point
public HttpBasicConfigurer<H> authenticationEntryPoint(AuthenticationEntryPoint authenticationEntryPoint);
// Security Context Configuration
public HttpBasicConfigurer<H> securityContextRepository(SecurityContextRepository securityContextRepository);
}Usage Example:
http.httpBasic(basic -> basic
.realmName("My Application")
.authenticationEntryPoint(customBasicAuthenticationEntryPoint())
);Configuration for OAuth2/OpenID Connect authentication.
public final class OAuth2LoginConfigurer<H extends HttpSecurityBuilder<H>>
extends AbstractAuthenticationFilterConfigurer<H, OAuth2LoginConfigurer<H>, OAuth2LoginAuthenticationFilter> {
// Client Registration
public OAuth2LoginConfigurer<H> clientRegistrationRepository(ClientRegistrationRepository clientRegistrationRepository);
public OAuth2LoginConfigurer<H> authorizedClientRepository(OAuth2AuthorizedClientRepository authorizedClientRepository);
public OAuth2LoginConfigurer<H> authorizedClientService(OAuth2AuthorizedClientService authorizedClientService);
// Login Page Configuration
public OAuth2LoginConfigurer<H> loginPage(String loginPage);
public OAuth2LoginConfigurer<H> loginProcessingUrl(String loginProcessingUrl);
// Endpoint Configuration
public OAuth2LoginConfigurer<H> authorizationEndpoint(Customizer<AuthorizationEndpointConfig> authorizationEndpointCustomizer);
public OAuth2LoginConfigurer<H> redirectionEndpoint(Customizer<RedirectionEndpointConfig> redirectionEndpointCustomizer);
public OAuth2LoginConfigurer<H> tokenEndpoint(Customizer<TokenEndpointConfig> tokenEndpointCustomizer);
public OAuth2LoginConfigurer<H> userInfoEndpoint(Customizer<UserInfoEndpointConfig> userInfoEndpointCustomizer);
// OIDC Configuration
public OAuth2LoginConfigurer<H> oidcLogout(Customizer<OidcLogoutConfigurer<H>> oidcLogoutCustomizer);
}Usage Example:
http.oauth2Login(oauth2 -> oauth2
.loginPage("/oauth2/authorization/google")
.authorizationEndpoint(authorization -> authorization
.baseUri("/oauth2/authorize")
.authorizationRequestRepository(cookieRequestRepository())
)
.tokenEndpoint(token -> token
.accessTokenResponseClient(accessTokenResponseClient())
)
.userInfoEndpoint(userInfo -> userInfo
.userService(oauth2UserService())
.oidcUserService(oidcUserService())
)
.successHandler(oauth2AuthenticationSuccessHandler())
.failureHandler(oauth2AuthenticationFailureHandler())
);Configuration for X.509 certificate authentication.
public final class X509Configurer<H extends HttpSecurityBuilder<H>>
extends AbstractHttpConfigurer<X509Configurer<H>, H> {
// Principal Extraction
public X509Configurer<H> subjectPrincipalRegex(String subjectPrincipalRegex);
public X509Configurer<H> x509PrincipalExtractor(X509PrincipalExtractor principalExtractor);
// User Details Service
public X509Configurer<H> userDetailsService(UserDetailsService userDetailsService);
// Authentication Details Source
public X509Configurer<H> authenticationDetailsSource(AuthenticationDetailsSource<HttpServletRequest, ?> authenticationDetailsSource);
}Usage Example:
http.x509(x509 -> x509
.subjectPrincipalRegex("CN=(.*?)(?:,|$)")
.userDetailsService(x509UserDetailsService())
);Modern HTTP request authorization configuration using AuthorizationManager.
public final class AuthorizeHttpRequestsConfigurer<H extends HttpSecurityBuilder<H>>
extends AbstractRequestMatcherRegistry<AuthorizeHttpRequestsConfigurer<H>.AuthorizationManagerRequestMatcherRegistry> {
public class AuthorizationManagerRequestMatcherRegistry extends AbstractRequestMatcherRegistry<AuthorizationManagerRequestMatcherRegistry> {
// Request Matching
public AuthorizationManagerRequestMatcherRegistry requestMatchers(String... patterns);
public AuthorizationManagerRequestMatcherRegistry requestMatchers(HttpMethod method, String... patterns);
public AuthorizationManagerRequestMatcherRegistry requestMatchers(RequestMatcher... requestMatchers);
public AuthorizationManagerRequestMatcherRegistry anyRequest();
// Authorization Rules
public AuthorizationManagerRequestMatcherRegistry permitAll();
public AuthorizationManagerRequestMatcherRegistry denyAll();
public AuthorizationManagerRequestMatcherRegistry authenticated();
public AuthorizationManagerRequestMatcherRegistry anonymous();
public AuthorizationManagerRequestMatcherRegistry rememberMe();
public AuthorizationManagerRequestMatcherRegistry fullyAuthenticated();
// Role-based Authorization
public AuthorizationManagerRequestMatcherRegistry hasRole(String role);
public AuthorizationManagerRequestMatcherRegistry hasAnyRole(String... roles);
public AuthorizationManagerRequestMatcherRegistry hasAuthority(String authority);
public AuthorizationManagerRequestMatcherRegistry hasAnyAuthority(String... authorities);
// IP-based Authorization
public AuthorizationManagerRequestMatcherRegistry hasIpAddress(String ipAddress);
// Custom Authorization
public AuthorizationManagerRequestMatcherRegistry access(AuthorizationManager<RequestAuthorizationContext> manager);
public AuthorizationManagerRequestMatcherRegistry access(String attribute);
}
}Usage Example:
http.authorizeHttpRequests(authz -> authz
.requestMatchers("/", "/home", "/public/**").permitAll()
.requestMatchers("/admin/**").hasRole("ADMIN")
.requestMatchers("/user/**").hasAnyRole("USER", "ADMIN")
.requestMatchers(HttpMethod.POST, "/api/**").hasAuthority("WRITE")
.requestMatchers("/internal/**").hasIpAddress("192.168.1.0/24")
.anyRequest().authenticated()
);Legacy expression-based URL authorization configuration.
public final class ExpressionUrlAuthorizationConfigurer<H extends HttpSecurityBuilder<H>>
extends AbstractInterceptUrlConfigurer<ExpressionUrlAuthorizationConfigurer<H>, H> {
public class ExpressionInterceptUrlRegistry extends AbstractRequestMatcherMappingConfigurer<List<AccessConfigAttribute>, ExpressionInterceptUrlRegistry> {
// Request Matching
public ExpressionInterceptUrlRegistry requestMatchers(String... patterns);
public ExpressionInterceptUrlRegistry requestMatchers(HttpMethod method, String... patterns);
public ExpressionInterceptUrlRegistry anyRequest();
// Authorization Rules
public ExpressionInterceptUrlRegistry permitAll();
public ExpressionInterceptUrlRegistry denyAll();
public ExpressionInterceptUrlRegistry authenticated();
public ExpressionInterceptUrlRegistry fullyAuthenticated();
public ExpressionInterceptUrlRegistry anonymous();
public ExpressionInterceptUrlRegistry rememberMe();
// Role-based Authorization
public ExpressionInterceptUrlRegistry hasRole(String role);
public ExpressionInterceptUrlRegistry hasAnyRole(String... roles);
public ExpressionInterceptUrlRegistry hasAuthority(String authority);
public ExpressionInterceptUrlRegistry hasAnyAuthority(String... authorities);
// IP-based Authorization
public ExpressionInterceptUrlRegistry hasIpAddress(String ipAddress);
// Expression-based Authorization
public ExpressionInterceptUrlRegistry access(String attribute);
}
}Configuration for Cross-Site Request Forgery protection.
public final class CsrfConfigurer<H extends HttpSecurityBuilder<H>>
extends AbstractHttpConfigurer<CsrfConfigurer<H>, H> {
// Token Repository
public CsrfConfigurer<H> csrfTokenRepository(CsrfTokenRepository csrfTokenRepository);
// Request Matching
public CsrfConfigurer<H> requireCsrfProtectionMatcher(RequestMatcher requireCsrfProtectionMatcher);
public CsrfConfigurer<H> ignoringRequestMatchers(RequestMatcher... requestMatchers);
public CsrfConfigurer<H> ignoringRequestMatchers(String... patterns);
// Session Authentication Strategy
public CsrfConfigurer<H> sessionAuthenticationStrategy(SessionAuthenticationStrategy sessionAuthenticationStrategy);
// Token Handler
public CsrfConfigurer<H> csrfTokenRequestHandler(CsrfTokenRequestHandler requestHandler);
}Usage Example:
http.csrf(csrf -> csrf
.csrfTokenRepository(CookieCsrfTokenRepository.withHttpOnlyFalse())
.ignoringRequestMatchers("/api/webhook/**")
.sessionAuthenticationStrategy(new ChangeSessionIdAuthenticationStrategy())
);Configuration for Cross-Origin Resource Sharing.
public class CorsConfigurer<H extends HttpSecurityBuilder<H>>
extends AbstractHttpConfigurer<CorsConfigurer<H>, H> {
// Configuration Source
public CorsConfigurer<H> configurationSource(CorsConfigurationSource configurationSource);
// Built-in Configuration
public CorsConfigurer<H> and();
}Usage Example:
http.cors(cors -> cors
.configurationSource(request -> {
CorsConfiguration config = new CorsConfiguration();
config.setAllowedOrigins(Arrays.asList("https://example.com"));
config.setAllowedMethods(Arrays.asList("GET", "POST", "PUT", "DELETE"));
config.setAllowedHeaders(Arrays.asList("*"));
config.setAllowCredentials(true);
return config;
})
);Configuration for security-related HTTP headers.
public final class HeadersConfigurer<H extends HttpSecurityBuilder<H>>
extends AbstractHttpConfigurer<HeadersConfigurer<H>, H> {
// Content Type Options
public HeadersConfigurer<H> contentTypeOptions(Customizer<ContentTypeOptionsConfig> contentTypeOptionsCustomizer);
// Frame Options
public HeadersConfigurer<H> frameOptions(Customizer<FrameOptionsConfig> frameOptionsCustomizer);
// HTTP Strict Transport Security
public HeadersConfigurer<H> httpStrictTransportSecurity(Customizer<HstsConfig> hstsCustomizer);
// Content Security Policy
public HeadersConfigurer<H> contentSecurityPolicy(String policyDirectives);
public HeadersConfigurer<H> contentSecurityPolicy(Customizer<ContentSecurityPolicyConfig> contentSecurityPolicyCustomizer);
// Referrer Policy
public HeadersConfigurer<H> referrerPolicy(ReferrerPolicy policy);
public HeadersConfigurer<H> referrerPolicy(Customizer<ReferrerPolicyConfig> referrerPolicyCustomizer);
// Cross-Origin Policies
public HeadersConfigurer<H> crossOriginEmbedderPolicy(CrossOriginEmbedderPolicy policy);
public HeadersConfigurer<H> crossOriginOpenerPolicy(CrossOriginOpenerPolicy policy);
public HeadersConfigurer<H> crossOriginResourcePolicy(CrossOriginResourcePolicy policy);
// Cache Control
public HeadersConfigurer<H> cacheControl(Customizer<CacheControlConfig> cacheControlCustomizer);
// Default Headers
public HeadersConfigurer<H> defaultsDisabled();
}Usage Example:
http.headers(headers -> headers
.frameOptions(frameOptions -> frameOptions.sameOrigin())
.contentSecurityPolicy("default-src 'self'; script-src 'self' 'unsafe-inline'")
.httpStrictTransportSecurity(hsts -> hsts
.maxAgeInSeconds(31536000)
.includeSubdomains(true)
.preload(true)
)
.referrerPolicy(ReferrerPolicy.STRICT_ORIGIN_WHEN_CROSS_ORIGIN)
);Configuration for HTTP session management and security.
public final class SessionManagementConfigurer<H extends HttpSecurityBuilder<H>>
extends AbstractHttpConfigurer<SessionManagementConfigurer<H>, H> {
// Session Creation Policy
public SessionManagementConfigurer<H> sessionCreationPolicy(SessionCreationPolicy sessionCreationPolicy);
// Session Authentication Strategy
public SessionManagementConfigurer<H> sessionAuthenticationStrategy(SessionAuthenticationStrategy sessionAuthenticationStrategy);
// Session Fixation Protection
public SessionManagementConfigurer<H> sessionFixation(Customizer<SessionFixationConfigurer> sessionFixationCustomizer);
// Concurrent Sessions
public SessionManagementConfigurer<H> maximumSessions(int maximumSessions);
public SessionManagementConfigurer<H> maxSessionsPreventsLogin(boolean maxSessionsPreventsLogin);
public SessionManagementConfigurer<H> sessionRegistry(SessionRegistry sessionRegistry);
public SessionManagementConfigurer<H> expiredUrl(String expiredUrl);
public SessionManagementConfigurer<H> expiredSessionStrategy(SessionInformationExpiredStrategy expiredSessionStrategy);
// Invalid Session Handling
public SessionManagementConfigurer<H> invalidSessionUrl(String invalidSessionUrl);
public SessionManagementConfigurer<H> invalidSessionStrategy(InvalidSessionStrategy invalidSessionStrategy);
}Usage Example:
http.sessionManagement(session -> session
.sessionCreationPolicy(SessionCreationPolicy.IF_REQUIRED)
.maximumSessions(1)
.maxSessionsPreventsLogin(false)
.expiredUrl("/session-expired")
.sessionRegistry(sessionRegistry())
.and()
.sessionFixation(sessionFixation -> sessionFixation.migrateSession())
.invalidSessionUrl("/login")
);Configuration for logout functionality and handlers.
public final class LogoutConfigurer<H extends HttpSecurityBuilder<H>>
extends AbstractHttpConfigurer<LogoutConfigurer<H>, H> {
// Logout URL Configuration
public LogoutConfigurer<H> logoutUrl(String logoutUrl);
public LogoutConfigurer<H> logoutRequestMatcher(RequestMatcher logoutRequestMatcher);
// Success Handling
public LogoutConfigurer<H> logoutSuccessUrl(String logoutSuccessUrl);
public LogoutConfigurer<H> logoutSuccessHandler(LogoutSuccessHandler logoutSuccessHandler);
// Session Invalidation
public LogoutConfigurer<H> invalidateHttpSession(boolean invalidateHttpSession);
// Cookie Deletion
public LogoutConfigurer<H> deleteCookies(String... cookieNamesToClear);
// Logout Handlers
public LogoutConfigurer<H> addLogoutHandler(LogoutHandler logoutHandler);
// Security Context
public LogoutConfigurer<H> clearAuthentication(boolean clearAuthentication);
// Permission Configuration
public LogoutConfigurer<H> permitAll();
public LogoutConfigurer<H> permitAll(boolean permitAll);
}Usage Example:
http.logout(logout -> logout
.logoutUrl("/logout")
.logoutSuccessUrl("/login?logout")
.invalidateHttpSession(true)
.deleteCookies("JSESSIONID", "remember-me")
.addLogoutHandler(customLogoutHandler())
.logoutSuccessHandler((request, response, authentication) -> {
response.sendRedirect("/goodbye");
})
.clearAuthentication(true)
.permitAll()
);Configuration for security exception handling.
public final class ExceptionHandlingConfigurer<H extends HttpSecurityBuilder<H>>
extends AbstractHttpConfigurer<ExceptionHandlingConfigurer<H>, H> {
// Authentication Entry Point
public ExceptionHandlingConfigurer<H> authenticationEntryPoint(AuthenticationEntryPoint authenticationEntryPoint);
// Access Denied Handling
public ExceptionHandlingConfigurer<H> accessDeniedHandler(AccessDeniedHandler accessDeniedHandler);
public ExceptionHandlingConfigurer<H> accessDeniedPage(String accessDeniedUrl);
// Default Entry Point Configuration
public ExceptionHandlingConfigurer<H> defaultAuthenticationEntryPointFor(AuthenticationEntryPoint entryPoint, RequestMatcher preferredMatcher);
}Usage Example:
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");
})
.accessDeniedPage("/access-denied")
);Configuration for request caching during authentication flows.
public final class RequestCacheConfigurer<H extends HttpSecurityBuilder<H>>
extends AbstractHttpConfigurer<RequestCacheConfigurer<H>, H> {
// Request Cache Implementation
public RequestCacheConfigurer<H> requestCache(RequestCache requestCache);
// Request Matchers
public RequestCacheConfigurer<H> requestMatchers(RequestMatcher... requestMatchers);
}Usage Example:
http.requestCache(cache -> cache
.requestCache(new HttpSessionRequestCache())
.requestMatchers(new AntPathRequestMatcher("/secure/**"))
);Install with Tessl CLI
npx tessl i tessl/maven-org-springframework-security--spring-security-config