CORS, CSRF, and Security Headers in Spring Boot: A Practical Guide

You've built a beautiful Spring Boot REST API. It's tested locally, works perfectly with Postman, and you're ready to deploy. Then the frontend team calls: "We're getting CORS errors in the browser." You add @CrossOrigin on every controller, push to production, and next week you find a CSRF vulnerability report from a security audit. Sound familiar? I've been there—twice, on the same project, before I learned to treat CORS, CSRF, and security headers as a single coherent defense layer, not three separate checkboxes.

In this guide, we'll walk through Spring Boot 3.2 with Spring Security 6.2, covering real-world configurations that have survived PCI-DSS audits, handled millions of requests per day, and—most importantly—prevented actual incidents. We'll start with what these protections are, move into the official documentation's blind spots, and end with a production incident that cost a fintech startup $12,000 in fraudulent transactions.

You'll learn why the default @CrossOrigin annotation is rarely sufficient, when to disable CSRF (and when absolutely not to), and how to set security headers that satisfy both security scanners and browser compatibility. By the end, you'll have a configuration template you can drop into any project with confidence. No more guessing, no more firefighting cross-origin issues at 2 AM.

Understanding CORS in Spring Boot 3.x

CORS (Cross-Origin Resource Sharing) is a browser-enforced security mechanism that controls which origins (domains) are allowed to access your API. In Spring Boot 3.x with Spring Security 6.x, CORS configuration has changed significantly from the old WebSecurityConfigurerAdapter approach. The browser sends a preflight OPTIONS request before the actual request, and your server must respond with appropriate Access-Control-* headers.

Here's the most common mistake: using @CrossOrigin on individual controllers or methods. While it works for simple cases, it becomes unmanageable as your API grows. You'll end up with inconsistent origins, missing headers, and debugging nightmares. The correct approach is a global CorsConfigurationSource bean.

Let's look at a production-ready CORS configuration for a SaaS billing API that serves a React frontend on app.example.com and a public REST API for third-party integrations.

@Configuration
public class CorsConfig {

    @Bean
    public CorsConfigurationSource corsConfigurationSource() {
        CorsConfiguration configuration = new CorsConfiguration();
        configuration.setAllowedOrigins(List.of(
            "https://app.example.com",
            "https://admin.example.com"
        ));
        configuration.setAllowedMethods(List.of("GET", "POST", "PUT", "DELETE", "PATCH"));
        configuration.setAllowedHeaders(List.of("*"));
        configuration.setExposedHeaders(List.of("X-Request-Id", "X-RateLimit-Remaining"));
        configuration.setAllowCredentials(true);
        configuration.setMaxAge(3600L);

        UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
        source.registerCorsConfiguration("/api/**", configuration);
        source.registerCorsConfiguration("/public/**", new CorsConfiguration().applyPermitDefaultValues());
        return source;
    }
}

What the Official Docs Won't Tell You

The Spring Security reference documentation is technically correct but practically incomplete. Here are three things I learned the hard way:

1. CORS and CSRF interact in subtle ways. If you disable CSRF (common for REST APIs), the CORS preflight handler still runs, but the actual request may fail if your security filter chain order is wrong. Spring Security 6.x requires that CorsFilter runs before the security filters. If you're using an older configuration or a custom filter, you'll get cryptic 403 errors for valid cross-origin requests.
2. @CrossOrigin on @Controller is not enough for error responses. When Spring Boot returns a 4xx or 5xx error, the error dispatcher doesn't include CORS headers. Your frontend will see a generic CORS error in the browser console, even though the real issue is a 500 on the server. You must configure a global CORS filter that handles all responses, including errors.
3. Security headers like X-Frame-Options are silently ignored in modern browsers. Chrome and Firefox have deprecated X-Frame-Options in favor of Content-Security-Policy's frame-ancestors directive. If you only set X-Frame-Options, your app is still vulnerable to clickjacking in newer browsers. Always set both for backward compatibility, but rely on CSP.

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .cors(cors -> cors.configurationSource(corsConfigurationSource()))
            .csrf(csrf -> csrf.disable()) // Only for stateless APIs
            .headers(headers -> headers
                .xssProtection(xss -> xss.disable())
                .contentSecurityPolicy(csp -> csp
                    .policyDirectives("frame-ancestors 'self'; script-src 'self'")
                )
                .frameOptions(frame -> frame.sameOrigin())
            )
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/api/public/**").permitAll()
                .anyRequest().authenticated()
            );
        return http.build();
    }

    @Bean
    public CorsConfigurationSource corsConfigurationSource() {
        // ... same as previous section
    }
}

CSRF Protection: When to Enable and When to Disable

CSRF (Cross-Site Request Forgery) protection prevents malicious websites from tricking a user's browser into making unauthorized requests to your application. Spring Security enables CSRF by default for any state-changing operation (POST, PUT, DELETE, PATCH). However, the decision to enable or disable CSRF depends entirely on your authentication mechanism.

Enable CSRF when: You use cookie-based authentication (session), your app serves a traditional multi-page application (MPA), or you have forms that submit data. CSRF tokens are typically embedded in forms or sent via a custom header (X-CSRF-TOKEN). Spring Security automatically generates and validates these tokens.

Disable CSRF when: You use stateless authentication like JWT with Bearer tokens (sent via Authorization header), or your API is consumed exclusively by non-browser clients (mobile apps, server-to-server). In these cases, the browser's same-origin policy is not the attack vector—the token itself is the credential.

The gray area is SPAs (Single Page Applications) with JWT stored in cookies. Many teams disable CSRF thinking JWT is sufficient, but if the JWT is sent via a cookie (which the browser automatically attaches), you're still vulnerable. The fix is to store JWT in memory or localStorage and send it via Authorization header, or use SameSite=Strict on the cookie.

@Configuration
@EnableWebSecurity
public class CsrfConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .csrf(csrf -> csrf
                .csrfTokenRepository(CookieCsrfTokenRepository.withHttpOnlyFalse())
                .csrfTokenRequestHandler(new CsrfTokenRequestAttributeHandler())
                .ignoringRequestMatchers("/api/public/**")
            )
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/api/public/**").permitAll()
                .anyRequest().authenticated()
            );
        return http.build();
    }

    @Bean
    public CsrfTokenRequestAttributeHandler csrfTokenRequestHandler() {
        CsrfTokenRequestAttributeHandler handler = new CsrfTokenRequestAttributeHandler();
        handler.setCsrfRequestAttributeName("_csrf");
        return handler;
    }
}

Security Headers: The Last Line of Defense

Security headers are HTTP response headers that instruct the browser to enforce additional security policies. They don't prevent all attacks, but they raise the bar significantly. In Spring Boot, you configure these via the HttpSecurity.headers() DSL.

Critical headers for any production API: - Strict-Transport-Security (HSTS): Forces HTTPS only. Set max-age=31536000 and includeSubDomains. Never enable preload without testing. - X-Content-Type-Options: nosniff: Prevents MIME type sniffing. Without this, a browser might interpret a user-uploaded file as executable JavaScript. - X-Frame-Options: DENY or SAMEORIGIN: Prevents clickjacking by controlling whether your site can be embedded in an iframe. - Content-Security-Policy (CSP): The most powerful header. Controls which resources (scripts, styles, images, fonts) can be loaded and executed. A strict CSP can mitigate XSS even if an attacker injects malicious code. - Referrer-Policy: strict-origin-when-cross-origin: Controls how much referrer information is sent with requests. - Permissions-Policy: Controls browser features like geolocation, camera, microphone.

Spring Security 6.x provides a fluent API for all these headers. However, be careful with CSP—too strict and you'll break legitimate functionality like inline scripts or CDN-loaded libraries.

@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
    http
        .headers(headers -> headers
            .httpStrictTransportSecurity(hsts -> hsts
                .includeSubDomains(true)
                .maxAgeInSeconds(31536000)
                .preload(false)
            )
            .contentTypeOptions(Customizer.withDefaults())
            .frameOptions(frame -> frame.deny())
            .xssProtection(xss -> xss.disable()) // Deprecated, use CSP
            .contentSecurityPolicy(csp -> csp
                .policyDirectives(
                    "default-src 'self'; " +
                    "script-src 'self' https://cdn.example.com; " +
                    "style-src 'self' 'unsafe-inline'; " +
                    "img-src 'self' data:; " +
                    "frame-ancestors 'none'; " +
                    "form-action 'self'"
                )
            )
            .referrerPolicy(referrer -> referrer
                .policy(ReferrerPolicy.STRICT_ORIGIN_WHEN_CROSS_ORIGIN)
            )
            .permissionsPolicy(permissions -> permissions
                .policy("geolocation=(), camera=(), microphone=()")
            )
        );
    return http.build();
}

Integrating CORS, CSRF, and Headers in a Single Configuration

In a real-world Spring Boot application, you need all three protections working together. The key is the order of configuration in the SecurityFilterChain. Spring Security 6.x processes filters in a specific sequence: CORS filter first, then CSRF, then security headers, then authentication, then authorization.

Here's a complete configuration for a typical SaaS application that has: - A React frontend on app.example.com - A public API for third-party integrations - Cookie-based authentication for admin users - JWT Bearer token for API clients

Notice how we use different CORS configurations for different paths: the public API allows any origin (no credentials), while the admin API restricts to the frontend domain with credentials enabled. CSRF is enabled only for cookie-authenticated paths.

@Configuration
@EnableWebSecurity
public class CompleteSecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .cors(cors -> cors.configurationSource(corsConfigurationSource()))
            .csrf(csrf -> csrf
                .csrfTokenRepository(CookieCsrfTokenRepository.withHttpOnlyFalse())
                .ignoringRequestMatchers("/api/public/**", "/api/v2/**")
            )
            .headers(headers -> headers
                .httpStrictTransportSecurity(hsts -> hsts
                    .includeSubDomains(true).maxAgeInSeconds(31536000))
                .contentTypeOptions(Customizer.withDefaults())
                .frameOptions(frame -> frame.sameOrigin())
                .contentSecurityPolicy(csp -> csp
                    .policyDirectives("default-src 'self'; frame-ancestors 'self'"))
                .referrerPolicy(referrer -> referrer
                    .policy(ReferrerPolicy.STRICT_ORIGIN_WHEN_CROSS_ORIGIN))
            )
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/api/public/**").permitAll()
                .requestMatchers("/api/admin/**").hasRole("ADMIN")
                .anyRequest().authenticated()
            )
            .oauth2ResourceServer(oauth2 -> oauth2.jwt(Customizer.withDefaults()));
        return http.build();
    }

    @Bean
    public CorsConfigurationSource corsConfigurationSource() {
        CorsConfiguration adminConfig = new CorsConfiguration();
        adminConfig.setAllowedOrigins(List.of("https://app.example.com"));
        adminConfig.setAllowedMethods(List.of("GET", "POST", "PUT", "DELETE"));
        adminConfig.setAllowedHeaders(List.of("*"));
        adminConfig.setAllowCredentials(true);
        adminConfig.setMaxAge(3600L);

        CorsConfiguration publicConfig = new CorsConfiguration();
        publicConfig.applyPermitDefaultValues();

        UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
        source.registerCorsConfiguration("/api/admin/**", adminConfig);
        source.registerCorsConfiguration("/api/public/**", publicConfig);
        return source;
    }
}

Testing CORS and Security Headers in Development

You cannot fully test CORS with Postman or curl alone—those tools don't enforce the same-origin policy. You need to simulate actual browser behavior. Here's a practical testing strategy:

1. Use curl to verify headers: Run curl -v -X OPTIONS -H "Origin: https://evil.com" -H "Access-Control-Request-Method: POST" https://api.example.com/api/endpoint. Check the response headers for Access-Control-Allow-Origin.
2. Create a simple HTML page for browser testing: Host a local HTML file that makes fetch requests to your API. Open it in a browser and check the console for CORS errors. This is the closest you can get to production behavior without deploying.
3. Use browser developer tools: The Network tab shows all request and response headers. Look for the presence of security headers like Strict-Transport-Security and Content-Security-Policy.
4. Automate with Spring Boot test: Use MockMvc with @WebMvcTest to test CORS configuration programmatically. You can set the Origin header and verify the response includes the correct CORS headers.
5. Security header scanners: Tools like Mozilla Observatory or securityheaders.com can scan your deployed endpoints and grade your security header configuration.

@WebMvcTest(controllers = TestController.class)
@AutoConfigureMockMvc
public class CorsTest {

    @Autowired
    private MockMvc mockMvc;

    @Test
    public void testCorsHeaders() throws Exception {
        mockMvc.perform(options("/api/test")
                .header("Origin", "https://app.example.com")
                .header("Access-Control-Request-Method", "POST"))
            .andExpect(status().isOk())
            .andExpect(header().string("Access-Control-Allow-Origin", 
                "https://app.example.com"))
            .andExpect(header().string("Access-Control-Allow-Methods",
                containsString("POST")));
    }

    @Test
    public void testCorsBlockedOrigin() throws Exception {
        mockMvc.perform(options("/api/test")
                .header("Origin", "https://evil.com")
                .header("Access-Control-Request-Method", "POST"))
            .andExpect(status().isForbidden());
    }

    @Test
    public void testSecurityHeaders() throws Exception {
        mockMvc.perform(get("/api/test"))
            .andExpect(header().string("Strict-Transport-Security",
                containsString("max-age=31536000")))
            .andExpect(header().string("X-Content-Type-Options", "nosniff"))
            .andExpect(header().string("X-Frame-Options", "DENY"));
    }
}

Common Pitfalls and How to Avoid Them

After years of debugging CORS and CSRF issues, here are the most common mistakes I've seen—and made:

Pitfall 1: Using @CrossOrigin on every controller. This leads to inconsistent configurations. One developer adds a new controller and forgets the annotation, causing mysterious failures. Solution: Use a global CorsConfigurationSource bean.

Pitfall 2: Disabling CSRF without understanding the implications. Many tutorials say "disable CSRF for REST APIs" without explaining why. If you use cookie-based auth or store JWT in cookies, you still need CSRF. Solution: Understand your authentication mechanism and test with a CSRF attack simulation.

Pitfall 3: Setting CSP too broadly. Allowing 'unsafe-inline' or 'unsafe-eval' defeats the purpose of CSP. But being too strict breaks legitimate functionality. Solution: Start with report-only mode, collect violations, then tighten gradually.

Pitfall 4: Forgetting to configure CORS for WebSocket endpoints. WebSocket connections have their own CORS mechanism (Origin header during handshake). Spring's WebSocket configuration has a separate setAllowedOrigins() method.

Pitfall 5: Ignoring error responses. As mentioned earlier, Spring Boot's error handling doesn't include CORS headers by default. Solution: Implement a custom ErrorController or use a filter that adds headers to all responses.

@Component
@Order(Ordered.HIGHEST_PRECEDENCE)
public class ErrorCorsFilter implements Filter {

    @Override
    public void doFilter(ServletRequest request, ServletResponse response,
                         FilterChain chain) throws IOException, ServletException {
        HttpServletResponse res = (HttpServletResponse) response;
        res.setHeader("Access-Control-Allow-Origin", "https://app.example.com");
        res.setHeader("Access-Control-Allow-Credentials", "true");
        res.setHeader("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE");
        res.setHeader("Access-Control-Allow-Headers", "*");
        chain.doFilter(request, response);
    }
}

Production Debugging Guide for CORS and Security Headers

When CORS or security header issues hit production, you need a systematic approach. Here's a step-by-step guide:

Step 1: Verify the request reaches your server. Use curl with -v to simulate the exact request the browser sends. If you get a response, the issue is likely on the browser side (CORS policy mismatch). If you get no response, check network connectivity and DNS.

Step 2: Check the preflight response. For non-simple requests (e.g., POST with JSON content-type), the browser sends an OPTIONS request first. Ensure your server responds with 200 OK and the correct Access-Control-* headers. Use curl -X OPTIONS -H "Origin: https://your-frontend.com" -H "Access-Control-Request-Method: POST" https://api.example.com/endpoint.

Step 3: Examine the actual request headers. If the preflight succeeds but the actual request fails, check that the actual response also includes CORS headers. Spring Security's CORS filter should add them to all responses, but custom filters or error handlers might strip them.

Step 4: Check browser console for CSP violations. If you see a CSP error, the browser will specify which directive was violated (e.g., "Refused to load script because it violates the following Content Security Policy directive..."). Use this to adjust your CSP policy.

Step 5: Enable Spring Security debug logging. Add logging.level.org.springframework.security=DEBUG to application.properties. This will show you which filters are invoked and whether CORS or CSRF tokens are being processed correctly.

# Enable detailed Spring Security logging for debugging
logging.level.org.springframework.security=DEBUG
logging.level.org.springframework.web.cors=TRACE

# For testing, you can disable HSTS in development
server.servlet.session.cookie.same-site=strict

# Custom CORS allowed origins (comma-separated)
app.cors.allowed-origins=https://app.example.com,https://admin.example.com