Spring Security

Every HTTP request passes through DelegatingFilterProxy (a standard servlet filter), which delegates to FilterChainProxy. FilterChainProxy matches the request against configured SecurityFilterChain beans (by URL pattern or other matchers) and passes the request through that chain's ordered filters. For a JWT-secured API, the key filters in order: 1. SecurityContextHolderFilter — loads or creates an empty SecurityContext. 2. CorsFilter — adds Access-Control-* headers (handles OPTIONS pre-flight). 3. CsrfFilter — validates CSRF token (disabled for stateless APIs). 4. BearerTokenAuthenticationFilter — extracts Authorization: Bearer <token>, calls AuthenticationManager, which calls JwtAuthenticationProvider, which validates the JWT and populates SecurityContext. 5. AnonymousAuthenticationFilter — sets an anonymous token if still unauthenticated. 6. ExceptionTranslationFilter — catches AuthenticationException (→ 401) and AccessDeniedException (→ 403). 7. AuthorizationFilter — evaluates authorizeHttpRequests() rules against the current Authentication. If denied, throws AccessDeniedException.

If all filters pass, the request reaches the DispatcherServlet and your controller.

Add spring-boot-starter-oauth2-resource-server. Configure the issuer: yaml spring: security: oauth2: resourceserver: jwt: issuer-uri: https://auth.example.com Spring Security auto-discovers the JWKS endpoint from issuer-uri/.well-known/openid-configuration, configures a NimbusJwtDecoder, and wires BearerTokenAuthenticationFilter. SecurityFilterChain configuration: java @Bean public SecurityFilterChain api(HttpSecurity http) throws Exception { return http .csrf(csrf -> csrf.disable()) .sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS)) .authorizeHttpRequests(a -> a .requestMatchers("/public/**").permitAll() .anyRequest().authenticated()) .oauth2ResourceServer(o -> o.jwt(Customizer.withDefaults())) .build(); } To map JWT claims to authorities (e.g., a roles claim): java @Bean public JwtAuthenticationConverter jwtAuthConverter() { JwtGrantedAuthoritiesConverter conv = new JwtGrantedAuthoritiesConverter(); conv.setAuthoritiesClaimName("roles"); conv.setAuthorityPrefix("ROLE_"); JwtAuthenticationConverter jac = new JwtAuthenticationConverter(); jac.setJwtGrantedAuthoritiesConverter(conv); return jac; }

CSRF (Cross-Site Request Forgery): a browser automatically includes cookies with cross-origin requests. An attacker on evil.com can make a user's browser send a POST to bank.com — if bank.com uses session cookies for auth, the request is authenticated. The CSRF token (a random value in a form field or header, not a cookie) prevents this — the attacker can't read the CSRF token from a different origin. When to disable: for stateless APIs using JWT Bearer tokens in Authorization headers. Bearer tokens are not automatically sent by browsers — the attacker can't forge an authenticated request. Disable: http.csrf(csrf -> csrf.disable()). Never disable for session-based apps that use cookies for authentication. CORS: configure via http.cors(Customizer.withDefaults()) + a CorsConfigurationSource bean. This ensures the CorsFilter runs before authentication filters, so OPTIONS pre-flight requests (which carry no credentials) are handled correctly: java @Bean public CorsConfigurationSource corsConfigurationSource() { CorsConfiguration config = new CorsConfiguration(); config.setAllowedOrigins(List.of("https://app.example.com")); config.setAllowedMethods(List.of("GET","POST","PUT","DELETE","OPTIONS")); config.setAllowedHeaders(List.of("Authorization","Content-Type")); config.setAllowCredentials(true); UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource(); source.registerCorsConfiguration("/**", config); return source; }

@PreAuthorize is a method security annotation that evaluates a Spring Expression Language (SpEL) expression before the method runs. If the expression returns false, AccessDeniedException is thrown (→ 403). Enable with @EnableMethodSecurity on a @Configuration class. Available in the SpEL context: - authentication — the current Authentication object - principal — authentication.getPrincipal() - hasRole('ADMIN') — checks for ROLE_ADMIN authority - hasAuthority('read:orders') — checks exact authority string - #variableName — references method parameter by name java @PreAuthorize("hasRole('ADMIN') or #userId == authentication.name") public UserProfile getProfile(String userId) { ... } Limitations: - Works via AOP proxy — self-calls within the same bean bypass the check silently. - Requires Spring context — testing the method directly without Spring bypasses security. - SpEL evaluation adds overhead on every call — for hot paths, consider HTTP-level rules.

@WebMvcTest with security enabled (default): the security filter chain runs during MockMvc tests. Without credentials, secured endpoints return 401/403. @WithMockUser: creates a mock authenticated user with specified roles: java @Test @WithMockUser(roles = "ADMIN") void adminEndpointReturns200() throws Exception { mockMvc.perform(get("/admin/dashboard")) .andExpect(status().isOk()); } @WithUserDetails("username"): loads an actual UserDetails from UserDetailsService — tests with real user data. SecurityMockMvcRequestPostProcessors: for JWT resource servers where @WithMockUser doesn't work (no session): java mockMvc.perform(get("/api/orders") .with(jwt().authorities(new SimpleGrantedAuthority("ROLE_USER")) .jwt(j -> j.claim("sub", "user123")))) .andExpect(status().isOk());

Full configuration for a stateless JWT resource server: ```java @Configuration @EnableMethodSecurity public class SecurityConfig {

@Bean public SecurityFilterChain api(HttpSecurity http) throws Exception { return http .csrf(csrf -> csrf.disable()) .cors(Customizer.withDefaults()) .sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS)) .authorizeHttpRequests(a -> a .requestMatchers("/actuator/health").permitAll() .requestMatchers("/api/public/**").permitAll() .anyRequest().authenticated()) .oauth2ResourceServer(o -> o .jwt(j -> j.jwtAuthenticationConverter(jwtAuthConverter())) .authenticationEntryPoint((req, res, ex) -> { res.setContentType("application/json"); res.setStatus(401); res.getWriter().write("{\"error\":\"Unauthorized\"}"); })) .build(); }

@Bean public JwtAuthenticationConverter jwtAuthConverter() { JwtGrantedAuthoritiesConverter conv = new JwtGrantedAuthoritiesConverter(); conv.setAuthoritiesClaimName("roles"); conv.setAuthorityPrefix("ROLE_"); JwtAuthenticationConverter jac = new JwtAuthenticationConverter(); jac.setJwtGrantedAuthoritiesConverter(conv); return jac; } } ```

hasRole("ADMIN") checks if the current user has an authority named ROLE_ADMIN. Spring Security automatically prepends ROLE_ to the argument. hasAuthority("ROLE_ADMIN") checks for the exact authority string ROLE_ADMIN. No prefix is added. Functionally, hasRole("ADMIN") == hasAuthority("ROLE_ADMIN") when your authorities follow the ROLE_ convention. When to use which: - Use hasRole("ADMIN") for role-based access following the ROLE_ convention. - Use hasAuthority("read:orders") for permission-based scopes (e.g., OAuth2 scopes) where the string is not a role and does not start with ROLE_.

Mixing them creates subtle bugs — hasRole("read:orders") checks for ROLE_read:orders, which never matches a scope authority.

Work through the filter chain systematically: 1. Enable security debug logging: logging.level.org.springframework.security=DEBUG. Security logs show every filter decision, the current Authentication, and the access decision for each request.

1. Check the access rule order: authorizeHttpRequests() rules match first-fit. A catch-all anyRequest().authenticated() before your permitAll() rules means everything is secured. Rules must go from most specific to most general.

2. Verify JWT decoder config: if using OAuth2 resource server, confirm the issuer-uri or jwk-set-uri is reachable from the service. A network issue at startup may have caused the JwtDecoder bean to fail silently.

3. Check @EnableMethodSecurity: if method security was added, a missing role on an endpoint that used to have none causes 403 (not 401).

4. Multiple SecurityFilterChain beans: if you have more than one, verify which chain matches the URL in question. Add a securityMatcher() to each to make matching explicit.

Correct CORS configuration requires two things: a CorsConfigurationSource bean and wiring it into Spring Security via http.cors(). java @Bean public CorsConfigurationSource corsConfigurationSource() { CorsConfiguration config = new CorsConfiguration(); config.setAllowedOrigins(List.of("https://app.example.com")); config.setAllowedMethods(List.of("GET", "POST", "PUT", "DELETE", "OPTIONS")); config.setAllowedHeaders(List.of("Authorization", "Content-Type", "X-Requested-With")); config.setExposedHeaders(List.of("X-Total-Count", "Link")); config.setAllowCredentials(true); config.setMaxAge(3600L); UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource(); source.registerCorsConfiguration("/**", config); return source; } In SecurityFilterChain: http.cors(Customizer.withDefaults()) — picks up the CorsConfigurationSource bean automatically. Why Spring Security must handle CORS (not just @CrossOrigin): OPTIONS pre-flight requests carry no credentials. If the CsrfFilter or authentication filter runs first, the OPTIONS request is rejected before the CORS headers are written. http.cors() inserts the CorsFilter before the auth filters.

Multi-tenancy in Spring Security requires making the tenant context part of the authentication and authorization decision. Step 1 — encode tenant in the token: include tenant_id (or similar) as a JWT claim. The JwtAuthenticationConverter maps it onto the Authentication object: java jac.setJwtGrantedAuthoritiesConverter(jwt -> { String tenantId = jwt.getClaimAsString("tenant_id"); List<GrantedAuthority> authorities = extractRoles(jwt, tenantId); return authorities; }); Step 2 — tenant-aware @PreAuthorize: inject the tenant from the JWT into SpEL: java @PreAuthorize("authentication.token.claims['tenant_id'] == #tenantId and hasRole('ADMIN')") public void adminAction(String tenantId) { ... } Step 3 — data isolation: use a TenantContextHolder (populated from the JWT in a filter) that Hibernate's CurrentTenantIdentifierResolver reads to apply row-level security or switch database schemas per tenant. Step 4 — role hierarchy per tenant: RoleHierarchy bean defines which roles imply others. For per-tenant hierarchies, resolve the hierarchy dynamically based on the current tenant context.

Spring MVC + @Async: SecurityContextHolder uses ThreadLocal by default. Async threads don't inherit it. Fix: configure DelegatingSecurityContextAsyncTaskExecutor: java @Bean public Executor taskExecutor() { return new DelegatingSecurityContextAsyncTaskExecutor( new ThreadPoolTaskExecutor() {{ initialize(); }}); } Spring WebFlux: ThreadLocal doesn't work in reactive pipelines (each operator may run on a different thread). Spring Security uses Reactor Context instead — ReactiveSecurityContextHolder. The SecurityContext is stored in the subscriber context and flows through the reactive chain automatically. Access in WebFlux: java ReactiveSecurityContextHolder.getContext() .map(SecurityContext::getAuthentication) .flatMap(auth -> process(auth)); @PreAuthorize works in WebFlux via ReactiveMethodSecurityExpressionHandler — enabled automatically with @EnableReactiveMethodSecurity.

Spring Security does not include rate limiting out of the box. Implementation options: Option 1 — Spring Security filter + Bucket4j (token bucket algorithm): ```java @Component public class RateLimitFilter extends OncePerRequestFilter { private final Bucket4jRateLimiter rateLimiter; // per-IP or per-user buckets

@Override protected void doFilterInternal(HttpServletRequest req, ...) { String key = extractKey(req); // IP or authenticated userId if (!rateLimiter.tryConsume(key)) { response.setStatus(429); return; } filterChain.doFilter(req, response); } } `` Register:http.addFilterBefore(rateLimitFilter, UsernamePasswordAuthenticationFilter.class). **Option 2 — Brute-force on login**: overrideAuthenticationEventPublisherto listen forAuthenticationFailureBadCredentialsEvent. Track failures per username/IP in Redis. After N failures in a window, lock the account (UserDetails.isAccountNonLocked()`) or add a delay. Option 3 — API gateway: implement rate limiting in Kong, AWS WAF, or Envoy before traffic reaches the service. Preferred for rate limits that apply across multiple services.

Migration goal: support both session-based (old) and JWT (new) clients simultaneously during the transition, then cut over. Phase 1 — dual auth chains: Configure two SecurityFilterChain beans. Chain 1 matches /api/v2/** (new clients, stateless JWT). Chain 2 matches everything else (existing clients, form login + sessions). Both chains coexist. New clients use JWT; old clients continue using sessions. Phase 2 — issue JWT alongside sessions (optional transition aid): After successful form login, generate a JWT and return it in the response body. Clients can start storing and using it. Phase 3 — migrate clients: Update each client (frontend, mobile, service) to use JWT Bearer tokens. Monitor session creation rate in Actuator metrics — when it drops to zero, all clients have migrated. Phase 4 — remove session chain: Remove Chain 2. Disable session creation globally. Clean up HttpSession infrastructure.

Centralized at the API gateway (authentication only): The gateway validates the token once (JWT signature, expiry, issuer), strips and re-emits claims in a trusted header (e.g., X-User-Id, X-User-Roles). Services trust the headers — no JWT validation overhead per service. Clean separation: one place to update token validation logic. Risk: services must trust that the gateway enforces authentication. A path that bypasses the gateway reaches services with no auth. Every internal service-to-service call must go through the gateway or a trusted mesh — or re-validate a service account token. Distributed in each service (authentication + authorization): Each service validates JWT and enforces its own access rules. More resilient — no gateway SPOF for auth. Fine-grained control: method-level @PreAuthorize with business logic. Consistent JWT validation via a shared library (internal Spring Security starter). Hybrid (recommended at scale): gateway handles rate limiting, mTLS termination, and coarse-grained auth (is the token valid?). Each service enforces fine-grained authorization with Spring Security. Service-to-service calls use short-lived service tokens (OAuth2 client credentials) validated by each service independently.

Zero-trust: every service-to-service call is authenticated, regardless of network location. No implicit trust because a call is on the internal network. OAuth2 Client Credentials (recommended): Each service is registered as an OAuth2 client. To call another service, it requests a token from the authorization server using its client ID and secret (or mTLS certificate). The called service validates the token as a resource server — same mechanism as user tokens. Spring Security 6 + Spring WebClient: java @Bean public WebClient serviceClient(OAuth2AuthorizedClientManager manager) { ServletOAuth2AuthorizedClientExchangeFilterFunction oauth2 = new ServletOAuth2AuthorizedClientExchangeFilterFunction(manager); oauth2.setDefaultClientRegistrationId("order-service"); return WebClient.builder().apply(oauth2.oauth2Configuration()).build(); } mTLS (stronger): Each service has a client certificate issued by an internal CA (Vault PKI). The called service validates the client cert. Spring Boot + Tomcat: configure clientAuth=want or need. Extract the client subject from X509Certificate in a custom filter. Combined mTLS + JWT: mTLS proves service identity at the transport layer; JWT carries claims at the application layer.