CORS

Browsers stop a page on https://app.example.com from reading responses from https://api.example.com unless the API says that origin is allowed. That permission system is CORS (Cross-Origin Resource Sharing). It is enforced by the browser only: curl, mobile apps and other servers ignore it entirely, so CORS is not access control. It just decides which websites may use your API from a visitor's browser.

Preflight requests

For anything beyond a simple GET, such as a POST with JSON, a PUT, or a request with an Authorization header, the browser first sends an OPTIONS preflight asking which methods and headers are allowed. That preflight carries no credentials. If Spring Security sees it before CORS is handled, it answers 401, and the browser reports a CORS error that hides the real cause.

That is why CORS must be handled by Spring Security itself. Call http.cors(Customizer.withDefaults()) and declare a CorsConfigurationSource bean. The CORS filter then runs early in the chain, answers preflights and adds the response headers to real requests. Spring Security also switches CORS on by itself when a UrlBasedCorsConfigurationSource bean exists, but writing cors() out keeps the intent visible in the configuration.

@Bean
CorsConfigurationSource corsConfigurationSource() {
    CorsConfiguration config = new CorsConfiguration();
    config.setAllowedOrigins(List.of("https://app.example.com"));
    config.setAllowedMethods(List.of("GET", "POST", "PUT", "DELETE"));
    config.setAllowedHeaders(List.of("Authorization", "Content-Type"));
    UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
    source.registerCorsConfiguration("/api/**", config);
    return source;
}

Settings worth understanding

• Allowed origins are scheme, host and port, with no path and no trailing slash. http://localhost:5173 and http://127.0.0.1:5173 are different origins.
• Credentials. If the front end sends cookies (credentials: 'include'), you need setAllowCredentials(true), and then a literal * origin is rejected. Use explicit origins, or setAllowedOriginPatterns for something like https://*.example.com.
• Exposed headers. JavaScript can only read a few response headers by default. Expose Location if the client follows it after a 201.
• Max age lets the browser cache a preflight answer so it is not repeated before every call.

Common mistakes

Allowing every origin with credentials is the dangerous one: any website a logged-in user visits could call your API as them. Keep the list in configuration so each environment allows its own front end, and never reflect the request's Origin header back blindly. Spring MVC's @CrossOrigin and addCorsMappings still exist, but with Spring Security on the classpath keep CORS in one place, the security configuration, so preflights are not rejected before MVC sees them. Actuator endpoints have their own management.endpoints.web.cors.* properties.