0
# Spring Security Config
1

2
Spring Security Config provides comprehensive declarative security configuration capabilities for Spring applications. It offers annotation-based configuration, fluent builders, and specialized configurers to define authentication, authorization, and security policies without programmatic filter chain construction.
3

4
## Package Information
5

6
- **Package Name**: org.springframework.security:spring-security-config
7
- **Package Type**: Maven/Gradle
8
- **Language**: Java
9
- **Version**: 6.5.1
10
- **Installation**: 
11
  ```xml
12
  <dependency>
13
    <groupId>org.springframework.security</groupId>
14
    <artifactId>spring-security-config</artifactId>
15
    <version>6.5.1</version>
16
  </dependency>
17
  ```
18

19
## Core Imports
20

21
```java
22
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
23
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
24
import org.springframework.security.config.annotation.web.builders.WebSecurity;
25
import org.springframework.security.config.annotation.authentication.builders.AuthenticationManagerBuilder;
26
import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity;
27
```
28

29
## Basic Usage
30

31
```java
32
@Configuration
33
@EnableWebSecurity
34
public class SecurityConfig {
35

36
    @Bean
37
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
38
        return http
39
            .authorizeHttpRequests(authz -> authz
40
                .requestMatchers("/public/**").permitAll()
41
                .anyRequest().authenticated()
42
            )
43
            .formLogin(form -> form
44
                .loginPage("/login")
45
                .permitAll()
46
            )
47
            .logout(logout -> logout.permitAll())
48
            .build();
49
    }
50

51
    @Bean
52
    public UserDetailsService userDetailsService() {
53
        UserDetails user = User.withDefaultPasswordEncoder()
54
            .username("user")
55
            .password("password")
56
            .roles("USER")
57
            .build();
58
        return new InMemoryUserDetailsManager(user);
59
    }
60
}
61
```
62

63
## Architecture
64

65
Spring Security Config uses a layered architecture:
66

67
1. **Annotations** - Enable security features and import configuration classes
68
2. **Builders** - Provide fluent APIs for constructing security objects
69
3. **Configurers** - Specialized components for specific security features
70
4. **Infrastructure** - Base classes and utilities supporting the configuration system
71

72
The module integrates with Spring's dependency injection container and follows the builder pattern for configuration flexibility.
73

74
## Capabilities
75

76
### Core Security Annotations
77

78
Essential annotations for enabling and configuring Spring Security features.
79

80
```java { .api }
81
@Target(ElementType.TYPE)
82
@Retention(RetentionPolicy.RUNTIME)
83
@Import({WebSecurityConfiguration.class, SpringWebMvcImportSelector.class, 
84
         OAuth2ImportSelector.class, HttpSecurityConfiguration.class})
85
@EnableGlobalAuthentication
86
public @interface EnableWebSecurity {
87
    boolean debug() default false;
88
}
89
```
90

91
```java { .api }
92
@Target(ElementType.TYPE)
93
@Retention(RetentionPolicy.RUNTIME)
94
@Import(MethodSecurityConfiguration.class)
95
public @interface EnableMethodSecurity {
96
    boolean prePostEnabled() default true;
97
    boolean securedEnabled() default false;
98
    boolean jsr250Enabled() default false;
99
    boolean proxyTargetClass() default false;
100
    AdviceMode mode() default AdviceMode.PROXY;
101
    int offset() default 0;
102
}
103
```
104

105
```java { .api }
106
@Target(ElementType.TYPE)
107
@Retention(RetentionPolicy.RUNTIME)
108
@Import(ReactiveMethodSecurityConfiguration.class)
109
public @interface EnableReactiveMethodSecurity {
110
    boolean proxyTargetClass() default false;
111
    AdviceMode mode() default AdviceMode.PROXY;
112
    int order() default Ordered.LOWEST_PRECEDENCE;
113
    boolean useAuthorizationManager() default true;
114
}
115
```
116

117
```java { .api }
118
@Target(ElementType.TYPE)
119
@Retention(RetentionPolicy.RUNTIME)
120
@Import({ServerHttpSecurityConfiguration.class, WebFluxSecurityConfiguration.class, 
121
         ReactiveOAuth2ClientImportSelector.class, ReactiveObservationImportSelector.class})
122
public @interface EnableWebFluxSecurity {
123
}
124
```
125

126
```java { .api }
127
@Target(ElementType.TYPE)
128
@Retention(RetentionPolicy.RUNTIME)
129
@Import({WebSocketMessageBrokerSecurityConfiguration.class, WebSocketObservationImportSelector.class})
130
public @interface EnableWebSocketSecurity {
131
}
132
```
133

134
```java { .api }
135
@Target(ElementType.TYPE)
136
@Retention(RetentionPolicy.RUNTIME)
137
@Import({RSocketSecurityConfiguration.class, SecuritySocketAcceptorInterceptorConfiguration.class, 
138
         ReactiveObservationImportSelector.class})
139
public @interface EnableRSocketSecurity {
140
}
141
```
142

143
```java { .api }
144
/** @deprecated Use @EnableMethodSecurity instead */
145
@Deprecated
146
@Target(ElementType.TYPE)
147
@Retention(RetentionPolicy.RUNTIME)
148
@Import(GlobalMethodSecurityConfiguration.class)
149
public @interface EnableGlobalMethodSecurity {
150
    boolean prePostEnabled() default false;
151
    boolean securedEnabled() default false;
152
    boolean jsr250Enabled() default false;
153
    boolean proxyTargetClass() default false;
154
    AdviceMode mode() default AdviceMode.PROXY;
155
    int order() default Ordered.LOWEST_PRECEDENCE;
156
}
157
```
158

159
[Core Security Annotations](./core-annotations.md)
160

161
### Security Builder Classes
162

163
Fluent API builders for constructing security configuration objects.
164

165
```java { .api }
166
public final class HttpSecurity extends AbstractConfiguredSecurityBuilder<DefaultSecurityFilterChain, HttpSecurity>
167
        implements SecurityBuilder<DefaultSecurityFilterChain>, HttpSecurityBuilder<HttpSecurity> {
168
    
169
    // Authorization Configuration
170
    public AuthorizeHttpRequestsConfigurer<HttpSecurity>.AuthorizationManagerRequestMatcherRegistry authorizeHttpRequests();
171
    public AuthorizeHttpRequestsConfigurer<HttpSecurity>.AuthorizationManagerRequestMatcherRegistry authorizeHttpRequests(
172
            Customizer<AuthorizeHttpRequestsConfigurer<HttpSecurity>.AuthorizationManagerRequestMatcherRegistry> authorizeHttpRequestsCustomizer);
173
    
174
    /** @deprecated Use authorizeHttpRequests() instead */
175
    @Deprecated
176
    public ExpressionUrlAuthorizationConfigurer<HttpSecurity>.ExpressionInterceptUrlRegistry authorizeRequests();
177
    /** @deprecated Use authorizeHttpRequests() instead */
178
    @Deprecated
179
    public ExpressionUrlAuthorizationConfigurer<HttpSecurity>.ExpressionInterceptUrlRegistry authorizeRequests(
180
            Customizer<ExpressionUrlAuthorizationConfigurer<HttpSecurity>.ExpressionInterceptUrlRegistry> authorizeRequestsCustomizer);
181
    
182
    // Authentication Methods
183
    public FormLoginConfigurer<HttpSecurity> formLogin();
184
    public FormLoginConfigurer<HttpSecurity> formLogin(Customizer<FormLoginConfigurer<HttpSecurity>> formLoginCustomizer);
185
    public HttpBasicConfigurer<HttpSecurity> httpBasic();
186
    public HttpBasicConfigurer<HttpSecurity> httpBasic(Customizer<HttpBasicConfigurer<HttpSecurity>> httpBasicCustomizer);
187
    public OAuth2LoginConfigurer<HttpSecurity> oauth2Login();
188
    public OAuth2LoginConfigurer<HttpSecurity> oauth2Login(Customizer<OAuth2LoginConfigurer<HttpSecurity>> oauth2LoginCustomizer);
189
    public OAuth2ClientConfigurer<HttpSecurity> oauth2Client();
190
    public OAuth2ClientConfigurer<HttpSecurity> oauth2Client(Customizer<OAuth2ClientConfigurer<HttpSecurity>> oauth2ClientCustomizer);
191
    public OAuth2ResourceServerConfigurer<HttpSecurity> oauth2ResourceServer();
192
    public OAuth2ResourceServerConfigurer<HttpSecurity> oauth2ResourceServer(Customizer<OAuth2ResourceServerConfigurer<HttpSecurity>> oauth2ResourceServerCustomizer);
193
    public Saml2LoginConfigurer<HttpSecurity> saml2Login();
194
    public Saml2LoginConfigurer<HttpSecurity> saml2Login(Customizer<Saml2LoginConfigurer<HttpSecurity>> saml2LoginCustomizer);
195
    public Saml2LogoutConfigurer<HttpSecurity> saml2Logout();
196
    public Saml2LogoutConfigurer<HttpSecurity> saml2Logout(Customizer<Saml2LogoutConfigurer<HttpSecurity>> saml2LogoutCustomizer);
197
    public Saml2MetadataConfigurer<HttpSecurity> saml2Metadata();
198
    public Saml2MetadataConfigurer<HttpSecurity> saml2Metadata(Customizer<Saml2MetadataConfigurer<HttpSecurity>> saml2MetadataCustomizer);
199
    public OidcLogoutConfigurer<HttpSecurity> oidcLogout();
200
    public OidcLogoutConfigurer<HttpSecurity> oidcLogout(Customizer<OidcLogoutConfigurer<HttpSecurity>> oidcLogoutCustomizer);
201
    public OneTimeTokenLoginConfigurer<HttpSecurity> oneTimeTokenLogin();
202
    public OneTimeTokenLoginConfigurer<HttpSecurity> oneTimeTokenLogin(Customizer<OneTimeTokenLoginConfigurer<HttpSecurity>> oneTimeTokenLoginCustomizer);
203
    public WebAuthnConfigurer<HttpSecurity> webAuthn(Customizer<WebAuthnConfigurer<HttpSecurity>> webAuthnCustomizer);
204
    public X509Configurer<HttpSecurity> x509();
205
    public X509Configurer<HttpSecurity> x509(Customizer<X509Configurer<HttpSecurity>> x509Customizer);
206
    public JeeConfigurer<HttpSecurity> jee();
207
    public JeeConfigurer<HttpSecurity> jee(Customizer<JeeConfigurer<HttpSecurity>> jeeCustomizer);
208
    public RememberMeConfigurer<HttpSecurity> rememberMe();
209
    public RememberMeConfigurer<HttpSecurity> rememberMe(Customizer<RememberMeConfigurer<HttpSecurity>> rememberMeCustomizer);
210
    public AnonymousConfigurer<HttpSecurity> anonymous();
211
    public AnonymousConfigurer<HttpSecurity> anonymous(Customizer<AnonymousConfigurer<HttpSecurity>> anonymousCustomizer);
212
    
213
    // Session and Security Context Management
214
    public SessionManagementConfigurer<HttpSecurity> sessionManagement();
215
    public SessionManagementConfigurer<HttpSecurity> sessionManagement(Customizer<SessionManagementConfigurer<HttpSecurity>> sessionManagementCustomizer);
216
    public SecurityContextConfigurer<HttpSecurity> securityContext();
217
    public SecurityContextConfigurer<HttpSecurity> securityContext(Customizer<SecurityContextConfigurer<HttpSecurity>> securityContextCustomizer);
218
    
219
    // Security Features
220
    public CsrfConfigurer<HttpSecurity> csrf();
221
    public CsrfConfigurer<HttpSecurity> csrf(Customizer<CsrfConfigurer<HttpSecurity>> csrfCustomizer);
222
    public CorsConfigurer<HttpSecurity> cors();
223
    public CorsConfigurer<HttpSecurity> cors(Customizer<CorsConfigurer<HttpSecurity>> corsCustomizer);
224
    public HeadersConfigurer<HttpSecurity> headers();
225
    public HeadersConfigurer<HttpSecurity> headers(Customizer<HeadersConfigurer<HttpSecurity>> headersCustomizer);
226
    public LogoutConfigurer<HttpSecurity> logout();
227
    public LogoutConfigurer<HttpSecurity> logout(Customizer<LogoutConfigurer<HttpSecurity>> logoutCustomizer);
228
    public RequireChannelConfigurer<HttpSecurity> requiresChannel();
229
    public RequireChannelConfigurer<HttpSecurity> requiresChannel(Customizer<RequireChannelConfigurer<HttpSecurity>> requiresChannelCustomizer);
230
    public HttpSecurity redirectToHttps();
231
    public PasswordManagementConfigurer<HttpSecurity> passwordManagement(Customizer<PasswordManagementConfigurer<HttpSecurity>> passwordManagementCustomizer);
232
    
233
    // Exception and Request Handling
234
    public ExceptionHandlingConfigurer<HttpSecurity> exceptionHandling();
235
    public ExceptionHandlingConfigurer<HttpSecurity> exceptionHandling(Customizer<ExceptionHandlingConfigurer<HttpSecurity>> exceptionHandlingCustomizer);
236
    public RequestCacheConfigurer<HttpSecurity> requestCache();
237
    public RequestCacheConfigurer<HttpSecurity> requestCache(Customizer<RequestCacheConfigurer<HttpSecurity>> requestCacheCustomizer);
238
    
239
    // Security Matchers and Configuration
240
    public SecurityMatcher securityMatchers();
241
    public SecurityMatcher securityMatchers(Customizer<SecurityMatcher> securityMatcherCustomizer);
242
    public HttpSecurity securityMatcher(RequestMatcher requestMatcher);
243
    public HttpSecurity securityMatcher(String... patterns);
244
    
245
    // Authentication Infrastructure
246
    public HttpSecurity authenticationManager(AuthenticationManager authenticationManager);
247
    public HttpSecurity authenticationProvider(AuthenticationProvider authenticationProvider);
248
    public HttpSecurity userDetailsService(UserDetailsService userDetailsService);
249
    
250
    // Filter Management
251
    public HttpSecurity addFilter(Filter filter);
252
    public HttpSecurity addFilterAfter(Filter filter, Class<? extends Filter> afterFilter);
253
    public HttpSecurity addFilterBefore(Filter filter, Class<? extends Filter> beforeFilter);
254
    public HttpSecurity addFilterAt(Filter filter, Class<? extends Filter> atFilter);
255
    
256
    // Final Build
257
    public DefaultSecurityFilterChain build() throws Exception;
258
}
259
```
260

261
```java { .api }
262
public final class WebSecurity extends AbstractConfiguredSecurityBuilder<Filter, WebSecurity>
263
        implements SecurityBuilder<Filter> {
264
    
265
    public WebSecurity ignoring();
266
    public WebSecurity debug(boolean debugEnabled);
267
    public WebSecurity httpFirewall(HttpFirewall httpFirewall);
268
    public Filter build() throws Exception;
269
}
270
```
271

272
[Security Builder Classes](./security-builders.md)
273

274
### HTTP Security Configurers
275

276
Specialized configurers for authentication, authorization, and security protection.
277

278
```java { .api }
279
public final class FormLoginConfigurer<H extends HttpSecurityBuilder<H>> 
280
        extends AbstractAuthenticationFilterConfigurer<H, FormLoginConfigurer<H>, UsernamePasswordAuthenticationFilter> {
281
    
282
    public FormLoginConfigurer<H> loginPage(String loginPage);
283
    public FormLoginConfigurer<H> defaultSuccessUrl(String defaultSuccessUrl);
284
    public FormLoginConfigurer<H> failureUrl(String authenticationFailureUrl);
285
    public FormLoginConfigurer<H> usernameParameter(String usernameParameter);
286
    public FormLoginConfigurer<H> passwordParameter(String passwordParameter);
287
}
288
```
289

290
```java { .api }
291
public final class AuthorizeHttpRequestsConfigurer<H extends HttpSecurityBuilder<H>> 
292
        extends AbstractRequestMatcherRegistry<AuthorizeHttpRequestsConfigurer<H>.AuthorizationManagerRequestMatcherRegistry> {
293
    
294
    public AuthorizeHttpRequestsConfigurer<H>.AuthorizationManagerRequestMatcherRegistry requestMatchers(String... patterns);
295
    public AuthorizeHttpRequestsConfigurer<H>.AuthorizationManagerRequestMatcherRegistry requestMatchers(HttpMethod method, String... patterns);
296
    public AuthorizeHttpRequestsConfigurer<H>.AuthorizationManagerRequestMatcherRegistry anyRequest();
297
}
298
```
299

300
[HTTP Security Configurers](./http-configurers.md)
301

302
### OAuth2 and SAML2 Configuration
303

304
Modern authentication protocol configuration support.
305

306
```java { .api }
307
public final class OAuth2LoginConfigurer<H extends HttpSecurityBuilder<H>> 
308
        extends AbstractAuthenticationFilterConfigurer<H, OAuth2LoginConfigurer<H>, OAuth2LoginAuthenticationFilter> {
309
    
310
    public OAuth2LoginConfigurer<H> clientRegistrationRepository(ClientRegistrationRepository clientRegistrationRepository);
311
    public OAuth2LoginConfigurer<H> authorizedClientService(OAuth2AuthorizedClientService authorizedClientService);
312
    public OAuth2LoginConfigurer<H> userInfoEndpoint(Customizer<UserInfoEndpointConfig> userInfoEndpointCustomizer);
313
}
314
```
315

316
```java { .api }
317
public final class OAuth2ResourceServerConfigurer<H extends HttpSecurityBuilder<H>> 
318
        extends AbstractHttpConfigurer<OAuth2ResourceServerConfigurer<H>, H> {
319
    
320
    public OAuth2ResourceServerConfigurer<H> jwt(Customizer<JwtConfigurer> jwtCustomizer);
321
    public OAuth2ResourceServerConfigurer<H> opaqueToken(Customizer<OpaqueTokenConfigurer> opaqueTokenCustomizer);
322
    public OAuth2ResourceServerConfigurer<H> bearerTokenResolver(BearerTokenResolver bearerTokenResolver);
323
}
324
```
325

326
[OAuth2 and SAML2 Configuration](./oauth2-configuration.md)
327

328
### Authentication Configuration
329

330
User details services, authentication providers, and authentication managers.
331

332
```java { .api }
333
public class AuthenticationManagerBuilder 
334
        extends AbstractConfiguredSecurityBuilder<AuthenticationManager, AuthenticationManagerBuilder>
335
        implements ProviderManagerBuilder<AuthenticationManagerBuilder> {
336
    
337
    public InMemoryUserDetailsManagerConfigurer<AuthenticationManagerBuilder> inMemoryAuthentication();
338
    public JdbcUserDetailsManagerConfigurer<AuthenticationManagerBuilder> jdbcAuthentication();
339
    public LdapAuthenticationProviderConfigurer<AuthenticationManagerBuilder> ldapAuthentication();
340
    public DaoAuthenticationConfigurer<AuthenticationManagerBuilder, InMemoryUserDetailsManager> userDetailsService(UserDetailsService userDetailsService);
341
    public AuthenticationManagerBuilder authenticationProvider(AuthenticationProvider authenticationProvider);
342
}
343
```
344

345
[Authentication Configuration](./authentication-configuration.md)
346

347
### Method Security
348

349
Annotation-based method-level security configuration.
350

351
```java { .api }
352
@Target(ElementType.TYPE)
353
@Retention(RetentionPolicy.RUNTIME)
354
@Import(ReactiveMethodSecurityConfiguration.class)
355
public @interface EnableReactiveMethodSecurity {
356
    boolean proxyTargetClass() default false;
357
    AdviceMode mode() default AdviceMode.PROXY;
358
    int order() default Ordered.LOWEST_PRECEDENCE;
359
    boolean useAuthorizationManager() default true;
360
}
361
```
362

363
```java { .api }
364
public abstract class GlobalMethodSecurityConfiguration implements ImportAware, BeanClassLoaderAware {
365
    protected void configure(AuthenticationManagerBuilder auth) throws Exception;
366
    protected AccessDecisionManager accessDecisionManager();
367
    protected MethodSecurityExpressionHandler createExpressionHandler();
368
}
369
```
370

371
[Method Security Configuration](./method-security.md)
372

373
## Types
374

375
### Core Configuration Types
376

377
```java { .api }
378
public interface SecurityBuilder<O> {
379
    O build() throws Exception;
380
}
381
```
382

383
```java { .api }
384
public interface SecurityConfigurer<O, B extends SecurityBuilder<O>> {
385
    void init(B builder) throws Exception;
386
    void configure(B builder) throws Exception;
387
}
388
```
389

390
```java { .api }
391
public abstract class SecurityConfigurerAdapter<O, B extends SecurityBuilder<O>> 
392
        implements SecurityConfigurer<O, B> {
393
    public void init(B builder) throws Exception;
394
    public void configure(B builder) throws Exception;
395
    public B and();
396
    protected final O postProcess(O object);
397
}
398
```
399

400
### Customization Support
401

402
```java { .api }
403
@FunctionalInterface
404
public interface Customizer<T> {
405
    void customize(T t);
406
    
407
    static <T> Customizer<T> withDefaults() {
408
        return (t) -> {};
409
    }
410
}
411
```
412

413
```java { .api }
414
public interface ObjectPostProcessor<T> {
415
    <O extends T> O postProcess(O object);
416
}
417
```
418

419
### Constants
420

421
```java { .api }
422
public final class BeanIds {
423
    public static final String AUTHENTICATION_MANAGER = "org.springframework.security.authenticationManager";
424
    public static final String SPRING_SECURITY_FILTER_CHAIN = "org.springframework.security.filterChain";
425
    public static final String USER_DETAILS_SERVICE = "org.springframework.security.userDetailsService";
426
    public static final String FILTER_CHAIN_PROXY = "org.springframework.security.web.FilterChainProxy";
427
}
428
```