Spring Security Filter Chain — The Complete Deep Dive

// Simplified DelegatingFilterProxy — the bridge
public class DelegatingFilterProxy extends GenericFilterBean {
    private volatile Filter delegate; // Lazily resolved to FilterChainProxy

    @Override
    public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain) {
        if (delegate == null) {
            delegate = applicationContext.getBean("springSecurityFilterChain", Filter.class);
        }
        delegate.doFilter(req, res, chain);
    }
}

// FilterChainProxy — the dispatcher
public class FilterChainProxy extends GenericFilterBean {
    private List<SecurityFilterChain> filterChains;

    @Override
    public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain) {
        HttpServletRequest request = (HttpServletRequest) req;
        // Find FIRST matching chain (order matters!)
        for (SecurityFilterChain securityChain : filterChains) {
            if (securityChain.matches(request)) {
                List<Filter> filters = securityChain.getFilters();
                new VirtualFilterChain(chain, filters).doFilter(req, res);
                return;
            }
        }
        // No chain matched — proceed without security filters
        chain.doFilter(req, res);
    }
}

// SecurityFilterChain — the contract
public interface SecurityFilterChain {
    boolean matches(HttpServletRequest request);  // Does this chain handle this URL?
    List<Filter> getFilters();                    // The ordered security filters
}

// How it works internally (simplified)
public class SecurityContextHolderFilter extends GenericFilterBean {
    private SecurityContextRepository securityContextRepository;

    @Override
    public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain) {
        HttpServletRequest request = (HttpServletRequest) req;

        // LOAD context at request start
        SecurityContext context = securityContextRepository.loadContext(request);
        SecurityContextHolder.setContext(context);

        try {
            chain.doFilter(req, res); // Continue to next filter
        } finally {
            // SAVE context at request end (Spring Security 6 — explicit save)
            securityContextRepository.saveContext(
                SecurityContextHolder.getContext(), request, (HttpServletResponse) res);
            SecurityContextHolder.clearContext(); // Prevent ThreadLocal leaks
        }
    }
}

// Simplified internal logic
public class UsernamePasswordAuthenticationFilter extends AbstractAuthenticationProcessingFilter {

    public UsernamePasswordAuthenticationFilter() {
        super(new AntPathRequestMatcher("/login", "POST")); // Only POST /login
    }

    @Override
    public Authentication attemptAuthentication(HttpServletRequest request,
                                                 HttpServletResponse response) {
        String username = request.getParameter("username");
        String password = request.getParameter("password");

        UsernamePasswordAuthenticationToken token =
            new UsernamePasswordAuthenticationToken(username, password);

        return this.getAuthenticationManager().authenticate(token);
    }
}

// Core logic (simplified)
public class BasicAuthenticationFilter extends OncePerRequestFilter {

    @Override
    protected void doFilterInternal(HttpServletRequest request,
                                     HttpServletResponse response,
                                     FilterChain chain) {
        String header = request.getHeader("Authorization");

        if (header == null || !header.startsWith("Basic ")) {
            chain.doFilter(request, response); // Not Basic auth — skip
            return;
        }

        // Decode Base64 → "username:password"
        byte[] decoded = Base64.getDecoder().decode(header.substring(6));
        String[] credentials = new String(decoded).split(":", 2);

        UsernamePasswordAuthenticationToken token =
            new UsernamePasswordAuthenticationToken(credentials[0], credentials[1]);

        try {
            Authentication result = authenticationManager.authenticate(token);
            SecurityContextHolder.getContext().setAuthentication(result);
        } catch (AuthenticationException e) {
            SecurityContextHolder.clearContext();
            authenticationEntryPoint.commence(request, response, e); // 401 + WWW-Authenticate
            return;
        }

        chain.doFilter(request, response);
    }
}

// Simplified internal logic
public class ExceptionTranslationFilter extends GenericFilterBean {

    private AuthenticationEntryPoint authenticationEntryPoint;
    private AccessDeniedHandler accessDeniedHandler;

    @Override
    public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain) {
        try {
            chain.doFilter(req, res); // This calls AuthorizationFilter
        } catch (AuthenticationException ex) {
            // User is not authenticated at all — challenge them
            sendStartAuthentication(request, response, ex);
        } catch (AccessDeniedException ex) {
            Authentication auth = SecurityContextHolder.getContext().getAuthentication();
            if (isAnonymous(auth)) {
                // Anonymous user → treat as authentication required (401)
                sendStartAuthentication(request, response, new InsufficientAuthenticationException("Full auth required"));
            } else {
                // Authenticated user lacking permissions → 403
                accessDeniedHandler.handle(request, response, ex);
            }
        }
    }
}

// Simplified — the new AuthorizationFilter (Spring Security 6)
public class AuthorizationFilter extends GenericFilterBean {

    private AuthorizationManager<HttpServletRequest> authorizationManager;

    @Override
    public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain) {
        HttpServletRequest request = (HttpServletRequest) req;
        Authentication authentication = SecurityContextHolder.getContext().getAuthentication();

        AuthorizationDecision decision = authorizationManager.check(
            () -> authentication, request);

        if (decision != null && !decision.isGranted()) {
            throw new AccessDeniedException("Access Denied");
        }

        chain.doFilter(req, res); // Authorized — proceed to controller
    }
}

@Component
@RequiredArgsConstructor
public class JwtAuthenticationFilter extends OncePerRequestFilter {

    private final JwtDecoder jwtDecoder;
    private final UserDetailsService userDetailsService;

    private static final Logger log = LoggerFactory.getLogger(JwtAuthenticationFilter.class);

    @Override
    protected void doFilterInternal(HttpServletRequest request,
                                     HttpServletResponse response,
                                     FilterChain filterChain)
            throws ServletException, IOException {

        String header = request.getHeader(HttpHeaders.AUTHORIZATION);

        // No token? Let downstream filters handle (might be anonymous or other auth)
        if (header == null || !header.startsWith("Bearer ")) {
            filterChain.doFilter(request, response);
            return;
        }

        String token = header.substring(7);

        try {
            // Validate token (signature, expiry, issuer, audience)
            Jwt jwt = jwtDecoder.decode(token);

            // Extract user identity
            String username = jwt.getSubject();
            UserDetails userDetails = userDetailsService.loadUserByUsername(username);

            // Build authenticated token with authorities
            UsernamePasswordAuthenticationToken authentication =
                new UsernamePasswordAuthenticationToken(
                    userDetails,
                    null,  // Credentials cleared — we've already validated
                    userDetails.getAuthorities()
                );
            authentication.setDetails(new WebAuthenticationDetailsSource().buildDetails(request));

            // Set in SecurityContext — AuthorizationFilter will see this
            SecurityContextHolder.getContext().setAuthentication(authentication);

            log.debug("JWT authenticated user: {} with roles: {}",
                username, userDetails.getAuthorities());

        } catch (JwtException e) {
            // Token invalid — don't set auth, let ExceptionTranslationFilter handle as 401
            log.debug("JWT validation failed: {}", e.getMessage());
            SecurityContextHolder.clearContext();
        } catch (UsernameNotFoundException e) {
            // Token valid but user no longer exists in DB
            log.warn("JWT subject not found in database: {}", e.getMessage());
            SecurityContextHolder.clearContext();
        }

        filterChain.doFilter(request, response);
    }

    @Override
    protected boolean shouldNotFilter(HttpServletRequest request) {
        String path = request.getServletPath();
        // Skip JWT processing for public endpoints (performance optimization)
        return path.startsWith("/api/public/") ||
               path.startsWith("/actuator/health") ||
               path.equals("/api/auth/login");
    }
}

@Component
@RequiredArgsConstructor
public class ApiKeyAuthenticationFilter extends OncePerRequestFilter {

    private final ApiKeyRepository apiKeyRepository; // DB of valid keys + their permissions

    private static final String API_KEY_HEADER = "X-API-Key";
    private static final Logger log = LoggerFactory.getLogger(ApiKeyAuthenticationFilter.class);

    @Override
    protected void doFilterInternal(HttpServletRequest request,
                                     HttpServletResponse response,
                                     FilterChain filterChain)
            throws ServletException, IOException {

        String apiKey = request.getHeader(API_KEY_HEADER);

        if (apiKey == null || apiKey.isBlank()) {
            filterChain.doFilter(request, response); // Not an API key request
            return;
        }

        Optional<ApiKeyEntity> keyEntity = apiKeyRepository.findByKeyHash(
            DigestUtils.sha256Hex(apiKey) // Never store raw keys!
        );

        if (keyEntity.isPresent() && keyEntity.get().isActive()) {
            ApiKeyEntity key = keyEntity.get();

            // Create authentication with service identity
            List<GrantedAuthority> authorities = key.getScopes().stream()
                .map(scope -> new SimpleGrantedAuthority("SCOPE_" + scope))
                .collect(Collectors.toList());

            ApiKeyAuthenticationToken auth = new ApiKeyAuthenticationToken(
                key.getServiceName(), authorities);
            auth.setDetails(new WebAuthenticationDetailsSource().buildDetails(request));

            SecurityContextHolder.getContext().setAuthentication(auth);
            log.info("API key authenticated service: {}", key.getServiceName());
        } else {
            log.warn("Invalid or inactive API key attempted from IP: {}",
                request.getRemoteAddr());
            // Don't reject here — let downstream filters/authorization handle it
        }

        filterChain.doFilter(request, response);
    }

    @Override
    protected boolean shouldNotFilter(HttpServletRequest request) {
        // Only check API key for internal service endpoints
        return !request.getServletPath().startsWith("/internal/");
    }
}

@Component
@RequiredArgsConstructor
public class RateLimitingFilter extends OncePerRequestFilter {

    private final RateLimiterService rateLimiterService; // Backed by Redis or Bucket4j

    @Override
    protected void doFilterInternal(HttpServletRequest request,
                                     HttpServletResponse response,
                                     FilterChain filterChain)
            throws ServletException, IOException {

        String clientId = resolveClientId(request);

        RateLimitResult result = rateLimiterService.tryConsume(clientId);

        // Always set rate limit headers (even on success)
        response.setHeader("X-RateLimit-Limit", String.valueOf(result.getLimit()));
        response.setHeader("X-RateLimit-Remaining", String.valueOf(result.getRemaining()));
        response.setHeader("X-RateLimit-Reset", String.valueOf(result.getResetEpochSeconds()));

        if (!result.isAllowed()) {
            response.setStatus(HttpStatus.TOO_MANY_REQUESTS.value());
            response.setContentType(MediaType.APPLICATION_JSON_VALUE);
            response.getWriter().write("""
                {"error": "rate_limit_exceeded",
                 "message": "Too many requests. Retry after %d seconds.",
                 "retry_after": %d}
                """.formatted(result.getRetryAfterSeconds(), result.getRetryAfterSeconds()));
            return; // Short-circuit — don't call further filters
        }

        filterChain.doFilter(request, response);
    }

    private String resolveClientId(HttpServletRequest request) {
        Authentication auth = SecurityContextHolder.getContext().getAuthentication();
        if (auth != null && auth.isAuthenticated() && !(auth instanceof AnonymousAuthenticationToken)) {
            return "user:" + auth.getName();
        }
        // Fall back to IP for unauthenticated requests
        return "ip:" + request.getRemoteAddr();
    }
}

@Component
@RequiredArgsConstructor
public class TenantResolutionFilter extends OncePerRequestFilter {

    private final TenantRepository tenantRepository;

    private static final String TENANT_HEADER = "X-Tenant-ID";

    @Override
    protected void doFilterInternal(HttpServletRequest request,
                                     HttpServletResponse response,
                                     FilterChain filterChain)
            throws ServletException, IOException {

        String tenantId = resolveTenantId(request);

        if (tenantId == null) {
            response.setStatus(HttpServletResponse.SC_BAD_REQUEST);
            response.getWriter().write("""
                {"error": "missing_tenant", "message": "X-Tenant-ID header is required"}
                """);
            return;
        }

        if (!tenantRepository.exists(tenantId)) {
            response.setStatus(HttpServletResponse.SC_NOT_FOUND);
            response.getWriter().write("""
                {"error": "invalid_tenant", "message": "Tenant not found"}
                """);
            return;
        }

        // Set in ThreadLocal — available throughout the request
        TenantContext.setCurrentTenant(tenantId);

        try {
            filterChain.doFilter(request, response);
        } finally {
            TenantContext.clear(); // Prevent ThreadLocal leaks!
        }
    }

    private String resolveTenantId(HttpServletRequest request) {
        // Strategy 1: Header
        String fromHeader = request.getHeader(TENANT_HEADER);
        if (fromHeader != null) return fromHeader;

        // Strategy 2: Subdomain (tenant1.app.example.com)
        String host = request.getServerName();
        if (host.contains(".app.example.com")) {
            return host.split("\\.")[0];
        }

        return null;
    }

    @Override
    protected boolean shouldNotFilter(HttpServletRequest request) {
        // Health checks don't need tenant context
        return request.getServletPath().startsWith("/actuator/");
    }
}

@Component
public class RequestLoggingFilter extends OncePerRequestFilter {

    private static final String CORRELATION_HEADER = "X-Correlation-ID";
    private static final Logger log = LoggerFactory.getLogger(RequestLoggingFilter.class);

    @Override
    protected void doFilterInternal(HttpServletRequest request,
                                     HttpServletResponse response,
                                     FilterChain filterChain)
            throws ServletException, IOException {

        // Use incoming correlation ID or generate new one
        String correlationId = request.getHeader(CORRELATION_HEADER);
        if (correlationId == null || correlationId.isBlank()) {
            correlationId = UUID.randomUUID().toString();
        }

        // Add to MDC for structured logging
        MDC.put("correlationId", correlationId);
        // Add to response headers for client tracing
        response.setHeader(CORRELATION_HEADER, correlationId);

        long startTime = System.currentTimeMillis();

        try {
            log.info("→ {} {} from {} | User: {}",
                request.getMethod(), request.getRequestURI(),
                request.getRemoteAddr(), getCurrentUser());

            filterChain.doFilter(request, response);

        } finally {
            long duration = System.currentTimeMillis() - startTime;
            log.info("← {} {} | Status: {} | Duration: {}ms",
                request.getMethod(), request.getRequestURI(),
                response.getStatus(), duration);
            MDC.clear();
        }
    }

    private String getCurrentUser() {
        Authentication auth = SecurityContextHolder.getContext().getAuthentication();
        return (auth != null && auth.isAuthenticated()) ? auth.getName() : "anonymous";
    }
}

@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
    return http
        // BEFORE: Your filter runs first, then the reference filter
        .addFilterBefore(jwtFilter, UsernamePasswordAuthenticationFilter.class)

        // AFTER: The reference filter runs first, then yours
        .addFilterAfter(auditFilter, AuthorizationFilter.class)

        // AT: Your filter runs at the SAME position (doesn't replace — both execute!)
        .addFilterAt(customAuthFilter, UsernamePasswordAuthenticationFilter.class)
        .build();
}

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    // ═══════════════════════════════════════════════════════════
    // Chain 1: Health & public endpoints — NO SECURITY AT ALL
    // ═══════════════════════════════════════════════════════════
    @Bean
    @Order(0)
    public SecurityFilterChain healthChain(HttpSecurity http) throws Exception {
        return http
            .securityMatcher("/actuator/health", "/actuator/info", "/api/public/**")
            .authorizeHttpRequests(auth -> auth.anyRequest().permitAll())
            .csrf(csrf -> csrf.disable())
            .sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
            .build();
    }

    // ═══════════════════════════════════════════════════════════
    // Chain 2: REST API — Stateless JWT authentication
    // ═══════════════════════════════════════════════════════════
    @Bean
    @Order(1)
    public SecurityFilterChain apiChain(HttpSecurity http,
                                         JwtAuthenticationFilter jwtFilter) throws Exception {
        return http
            .securityMatcher("/api/**")
            .csrf(csrf -> csrf.disable()) // Stateless = no CSRF
            .sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
            .addFilterBefore(jwtFilter, UsernamePasswordAuthenticationFilter.class)
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/api/auth/**").permitAll()
                .requestMatchers("/api/admin/**").hasRole("ADMIN")
                .requestMatchers("/api/reports/**").hasAnyRole("ADMIN", "ANALYST")
                .anyRequest().authenticated()
            )
            .exceptionHandling(ex -> ex
                .authenticationEntryPoint((req, res, e) -> {
                    res.setStatus(401);
                    res.setContentType("application/json");
                    res.getWriter().write("""
                        {"error": "unauthorized", "message": "Bearer token required"}""");
                })
                .accessDeniedHandler((req, res, e) -> {
                    res.setStatus(403);
                    res.setContentType("application/json");
                    res.getWriter().write("""
                        {"error": "forbidden", "message": "Insufficient permissions"}""");
                })
            )
            .build();
    }

    // ═══════════════════════════════════════════════════════════
    // Chain 3: Web application — Session-based form login
    // ═══════════════════════════════════════════════════════════
    @Bean
    @Order(2)
    public SecurityFilterChain webChain(HttpSecurity http) throws Exception {
        return http
            .securityMatcher("/web/**", "/login", "/logout", "/css/**", "/js/**")
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/css/**", "/js/**", "/login").permitAll()
                .requestMatchers("/web/admin/**").hasRole("ADMIN")
                .anyRequest().authenticated()
            )
            .formLogin(form -> form
                .loginPage("/login")
                .loginProcessingUrl("/login")
                .defaultSuccessUrl("/web/dashboard")
                .failureUrl("/login?error=true")
            )
            .logout(logout -> logout
                .logoutUrl("/logout")
                .logoutSuccessUrl("/login?logout=true")
                .invalidateHttpSession(true)
                .deleteCookies("JSESSIONID")
            )
            .csrf(Customizer.withDefaults()) // CSRF enabled for browser forms
            .build();
    }

    // ═══════════════════════════════════════════════════════════
    // Chain 4: Actuator/monitoring — HTTP Basic for ops team
    // ═══════════════════════════════════════════════════════════
    @Bean
    @Order(3)
    public SecurityFilterChain actuatorChain(HttpSecurity http) throws Exception {
        return http
            .securityMatcher("/actuator/**")
            .authorizeHttpRequests(auth -> auth.anyRequest().hasRole("OPS"))
            .httpBasic(basic -> basic
                .realmName("Actuator")
                .authenticationEntryPoint(new BasicAuthenticationEntryPoint() {{
                    setRealmName("Actuator");
                }})
            )
            .sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
            .csrf(csrf -> csrf.disable())
            .build();
    }
}

@Configuration
@EnableWebSecurity
public class HybridAuthConfig {

    @Bean
    @Order(1)
    public SecurityFilterChain hybridApiChain(HttpSecurity http,
                                               JwtAuthenticationFilter jwtFilter,
                                               ApiKeyAuthenticationFilter apiKeyFilter)
            throws Exception {
        return http
            .securityMatcher("/api/**")
            .csrf(csrf -> csrf.disable())
            .sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
            // API key filter runs FIRST — if key present, authenticates as service
            .addFilterBefore(apiKeyFilter, UsernamePasswordAuthenticationFilter.class)
            // JWT filter runs SECOND — if Bearer token present, authenticates as user
            .addFilterBefore(jwtFilter, UsernamePasswordAuthenticationFilter.class)
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/api/internal/**").hasAuthority("SCOPE_internal")
                .requestMatchers("/api/admin/**").hasRole("ADMIN")
                .anyRequest().authenticated()
            )
            .build();
    }
}

@Bean
public SecurityFilterChain oauth2Chain(HttpSecurity http) throws Exception {
    return http
        .authorizeHttpRequests(auth -> auth.anyRequest().authenticated())
        .oauth2Login(oauth2 -> oauth2
            .authorizationEndpoint(a -> a.baseUri("/oauth2/authorize"))
            .redirectionEndpoint(r -> r.baseUri("/oauth2/callback/*"))
            .userInfoEndpoint(u -> u.userService(customOAuth2UserService()))
        )
        .build();
}

// ❌ Don't write new code like this
@Configuration
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
            .authorizeRequests()
                .antMatchers("/api/public/**").permitAll()
                .antMatchers("/api/admin/**").hasRole("ADMIN")
                .anyRequest().authenticated()
            .and()
            .httpBasic()
            .and()
            .csrf().disable();
    }

    @Override
    protected void configure(AuthenticationManagerBuilder auth) throws Exception {
        auth.userDetailsService(userDetailsService)
            .passwordEncoder(new BCryptPasswordEncoder());
    }

    @Bean
    @Override
    public AuthenticationManager authenticationManagerBean() throws Exception {
        return super.authenticationManagerBean();
    }
}

// ✅ Modern component-based configuration
@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        return http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/api/public/**").permitAll()
                .requestMatchers("/api/admin/**").hasRole("ADMIN")
                .anyRequest().authenticated()
            )
            .httpBasic(Customizer.withDefaults())
            .csrf(csrf -> csrf.disable())
            .build();
    }

    @Bean
    public AuthenticationManager authManager(AuthenticationConfiguration config)
            throws Exception {
        return config.getAuthenticationManager();
    }

    @Bean
    public UserDetailsService userDetailsService(UserRepository userRepo) {
        return username -> userRepo.findByUsername(username)
            .orElseThrow(() -> new UsernameNotFoundException("User not found: " + username));
    }

    @Bean
    public PasswordEncoder passwordEncoder() {
        return new BCryptPasswordEncoder();
    }
}

@Component
@Slf4j
public class FilterChainInspector implements CommandLineRunner {

    @Autowired
    private List<SecurityFilterChain> filterChains;

    @Override
    public void run(String... args) {
        log.info("╔══════════════════════════════════════════════════╗");
        log.info("║       SECURITY FILTER CHAIN CONFIGURATION       ║");
        log.info("╚══════════════════════════════════════════════════╝");

        for (int i = 0; i < filterChains.size(); i++) {
            SecurityFilterChain chain = filterChains.get(i);
            log.info("━━━ Chain {} ({} filters) ━━━", i + 1, chain.getFilters().size());
            for (int j = 0; j < chain.getFilters().size(); j++) {
                log.info("  {}. {}", j + 1,
                    chain.getFilters().get(j).getClass().getSimpleName());
            }
        }
    }
}

// TEMPORARY — remove before merging to main!
public class SecurityDebugFilter extends OncePerRequestFilter {

    private static final Logger log = LoggerFactory.getLogger(SecurityDebugFilter.class);

    @Override
    protected void doFilterInternal(HttpServletRequest request,
                                     HttpServletResponse response,
                                     FilterChain chain) throws ServletException, IOException {
        Authentication before = SecurityContextHolder.getContext().getAuthentication();
        log.debug("BEFORE chain — Auth: {}, Path: {} {}",
            before != null ? before.getClass().getSimpleName() + "(" + before.getName() + ")" : "NULL",
            request.getMethod(), request.getRequestURI());

        chain.doFilter(request, response);

        Authentication after = SecurityContextHolder.getContext().getAuthentication();
        log.debug("AFTER chain — Auth: {}, Status: {}",
            after != null ? after.getClass().getSimpleName() + "(" + after.getName() + ")" : "NULL",
            response.getStatus());
    }
}

// Prevent Spring Boot from auto-registering your filter as a servlet filter
@Bean
public FilterRegistrationBean<JwtAuthenticationFilter> jwtFilterRegistration(
        JwtAuthenticationFilter filter) {
    FilterRegistrationBean<JwtAuthenticationFilter> registration = new FilterRegistrationBean<>(filter);
    registration.setEnabled(false); // Don't register as servlet filter — only use in SecurityFilterChain
    return registration;
}

// Selective CSRF — disable for API, enable for web forms
.csrf(csrf -> csrf
    .ignoringRequestMatchers("/api/**", "/webhooks/**")
    // Web paths still protected
)

@Bean
public CorsConfigurationSource corsConfigurationSource() {
    CorsConfiguration config = new CorsConfiguration();
    config.setAllowedOrigins(List.of(
        "https://app.example.com",
        "https://admin.example.com"
    ));
    config.setAllowedMethods(List.of("GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"));
    config.setAllowedHeaders(List.of("Authorization", "Content-Type", "X-Request-ID"));
    config.setExposedHeaders(List.of("X-Total-Count", "X-Correlation-ID"));
    config.setAllowCredentials(true);
    config.setMaxAge(3600L); // Cache preflight for 1 hour

    UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
    source.registerCorsConfiguration("/api/**", config);
    return source;
}

@Bean
public SecurityFilterChain apiChain(HttpSecurity http) throws Exception {
    return http
        .cors(cors -> cors.configurationSource(corsConfigurationSource()))
        // ... rest of config
        .build();
}

// Propagate SecurityContext to @Async methods
@Configuration
@EnableAsync
public class AsyncConfig implements AsyncConfigurer {

    @Override
    public Executor getAsyncExecutor() {
        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
        executor.setCorePoolSize(10);
        executor.setMaxPoolSize(50);
        executor.initialize();
        // Wrap to propagate SecurityContext to async threads
        return new DelegatingSecurityContextExecutor(executor);
    }
}

// Option 1: DelegatingSecurityContextExecutor (recommended)
@Bean
public Executor taskExecutor() {
    return new DelegatingSecurityContextExecutor(
        Executors.newFixedThreadPool(10));
}

// Option 2: @Async with SecurityContextHolder strategy
// Set at app startup:
SecurityContextHolder.setStrategyName(SecurityContextHolder.MODE_INHERITABLETHREADLOCAL);

// Option 3: Manual propagation
CompletableFuture.supplyAsync(() -> {
    SecurityContext context = SecurityContextHolder.getContext(); // Captured in parent
    SecurityContextHolder.setContext(context); // Set in child
    try {
        return doWork();
    } finally {
        SecurityContextHolder.clearContext();
    }
}, executor);