Ch. 8 · Spring Boot

Spring CSRF Protection and Authentication Transport

When Spring Security CSRF protection is needed: cookie sessions vs bearer tokens, SameSite, CookieCsrfTokenRepository and SPA setups in Boot 3.

~6 min readadvancedupdated Nov 1, 2026

Plenty of Spring Security configurations contain csrf(csrf -> csrf.disable()), and the honest reason is often “POST requests returned 403 and this made it go away.” Whether that line is safe depends on what CSRF actually defends against, which comes down to one thing: how the credential travels. If the browser attaches it automatically, you need protection. If your JavaScript must attach it deliberately, you mostly do not. The configuration below uses Spring Boot 3.x with Spring Security 6 and its lambda DSL.

When CSRF protection is needed, and when it is not

Cross-site request forgery tricks a logged-in user’s browser into sending a state-changing request to your site from another origin. It works because browsers attach cookies automatically. Spring Security enables CSRF protection by default for unsafe methods (POST, PUT, PATCH, DELETE) and requires a token the attacker’s page cannot read. Keep it on for any cookie-authenticated application, including SPAs using a session cookie. It is reasonable to disable it for a stateless API that authenticates only with a bearer token in the Authorization header, because an attacker cannot make the browser add that header. SameSite cookies reduce the risk but do not replace tokens.

A forged transfer form, and how CsrfFilter stops it

An attacker hosts this page and lures a logged-in user to it:

<form action="https://bank.example.com/transfers" method="POST">
  <input name="to" value="attacker">
  <input name="amount" value="5000">
</form>
<script>document.forms[0].submit()</script>
Text

The browser sends the user’s SESSION cookie with the POST. The server sees an authenticated request. The attacker never needed to read anything.

Spring Security’s CsrfFilter blocks this by requiring a secret token, stored server side (session) or in a cookie, that must be echoed back in a header or form field. The attacker’s page can make the browser send cookies, but the same-origin policy prevents it from reading the token, so it cannot put the token in the request.

Since Spring Security 6, two details changed. The token is deferred, loaded only when something needs it, and it is masked with random bytes on each render (BREACH protection) by XorCsrfTokenRequestAttributeHandler. Server-rendered Thymeleaf forms handle both automatically through the hidden _csrf field. SPAs need deliberate configuration.

Configuring CSRF by how the credential travels

First question: how does the browser authenticate?

Ask how the browser authenticates. If it is a session cookie or a “remember me” cookie, CSRF protection is required. A JWT stored in a cookie is still a cookie, so protection is still required. A token held in memory by your JavaScript and sent as Authorization: Bearer ... is not exposed to classic CSRF.

A stateless bearer-token API

For a resource server that never creates sessions, disabling CSRF is legitimate, and you should say why in code:

@Bean
SecurityFilterChain api(HttpSecurity http) throws Exception {
    http.securityMatcher("/api/**")
        .authorizeHttpRequests(auth -> auth.anyRequest().authenticated())
        .oauth2ResourceServer(oauth -> oauth.jwt(Customizer.withDefaults()))
        .sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
        // Credentials arrive only in the Authorization header, which browsers never add on their own.
        .csrf(csrf -> csrf.disable());
    return http.build();
}
java

A React or Angular app served from the same site that logs in with a session cookie needs CSRF. Store the token in a readable cookie so JavaScript can copy it into a header:

@Bean
SecurityFilterChain web(HttpSecurity http) throws Exception {
    http.authorizeHttpRequests(auth -> auth.anyRequest().authenticated())
        .formLogin(Customizer.withDefaults())
        .csrf(csrf -> csrf
            .csrfTokenRepository(CookieCsrfTokenRepository.withHttpOnlyFalse())   // XSRF-TOKEN cookie
            .csrfTokenRequestHandler(new CsrfTokenRequestAttributeHandler()));    // accept the raw cookie value
    return http.build();
}
java

The client reads XSRF-TOKEN and sends it as X-XSRF-TOKEN. Angular’s HttpClient does this automatically for same-origin requests; Axios has xsrfCookieName and xsrfHeaderName options. The plain CsrfTokenRequestAttributeHandler is used because the SPA sends the unmasked cookie value; the Spring Security reference also shows a hybrid handler if you need BREACH protection for server-rendered pages in the same app.

Because tokens are deferred, the XSRF-TOKEN cookie appears only after something touches the token. If the SPA’s first request is a POST, it fails with 403. A small filter or an endpoint that loads the token fixes it:

@GetMapping("/api/csrf")
CsrfToken csrf(CsrfToken token) {
    return token;   // serializing the token loads it, which writes the cookie
}
java

SameSite as defense in depth

server:
  servlet:
    session:
      cookie:
        same-site: lax
        secure: true
        http-only: true
yaml

Lax stops cookies on cross-site POSTs in modern browsers, but older browsers, same-site subdomain attacks and top-level GET side effects remain. Keep the token.

An admin portal that shipped csrf.disable() after an upgrade

Picture a team that migrates an internal admin portal to Spring Boot 3. After the upgrade, every form submit from their single-page frontend returns 403. Someone adds .csrf(csrf -> csrf.disable()), the portal works, and the change ships.

The portal authenticates with a JSESSIONID cookie. A security review can now demonstrate a page on another domain that auto-submits a POST to /admin/users/42/roles while an admin is logged in, granting the attacker admin rights.

The original 403 had two real causes. The SPA sends the raw value from the XSRF-TOKEN cookie, while Spring Security 6’s default request handler expects a masked token, so the values never match. And because the token is deferred, no cookie exists before the first POST. The fix restores protection: re-enable CSRF with CookieCsrfTokenRepository.withHttpOnlyFalse() and CsrfTokenRequestAttributeHandler, add the /api/csrf bootstrap call on app start, and configure the HTTP client to send X-XSRF-TOKEN. A test then asserts that a POST without a token is rejected.

Five ways CSRF protection gets weakened

  • “We use JWT, so CSRF does not apply.” That holds only if the JWT travels in a header your code sets. A JWT in a cookie is a cookie, and the browser attaches it automatically.
  • “CORS protects us.” CORS controls whether a script can read a cross-origin response. A simple form POST is sent without a preflight, and the side effect happens anyway. See CORS configuration.
  • “SameSite=Lax is enough.” It is good defense in depth, not a complete control.
  • Making GET requests change state. CSRF protection skips safe methods by design; a GET /delete?id=5 is unprotected.
  • Disabling CSRF globally when only one webhook endpoint needs it. Use csrf.ignoringRequestMatchers("/webhooks/**") instead and authenticate the webhook with a signature.

Asserting both the 403 and the accepted POST

Spring Security’s test support makes both sides easy to assert:

@WebMvcTest(AdminController.class)
@Import(WebSecurityConfig.class)
class CsrfTest {

    @Autowired MockMvc mvc;

    @Test
    @WithMockUser(roles = "ADMIN")
    void postWithoutTokenIsForbidden() throws Exception {
        mvc.perform(post("/admin/users/42/roles").content("ADMIN"))
           .andExpect(status().isForbidden());
    }

    @Test
    @WithMockUser(roles = "ADMIN")
    void postWithTokenIsAccepted() throws Exception {
        mvc.perform(post("/admin/users/42/roles").content("ADMIN").with(csrf()))
           .andExpect(status().isOk());
    }
}
java

In a browser, open developer tools and confirm the XSRF-TOKEN cookie exists and the X-XSRF-TOKEN header is on each mutating request.

Follow-ups on safe methods, readable cookies and BREACH

Why are safe methods exempt? GET, HEAD, OPTIONS and TRACE should not change state, so forging them gains nothing. That only holds if your application respects HTTP semantics.

Why must the cookie be readable (HttpOnly false)? The double-submit pattern relies on JavaScript reading the cookie and copying it into a header. The session cookie itself stays HttpOnly.

What does BREACH have to do with CSRF tokens? BREACH extracts secrets from compressed HTTPS responses. Masking the token differently on every response defeats it, which is why Spring Security 6 masks by default.

How do you handle logout? Logout should be a POST with a token; a GET logout lets any page log your users out.

Practice question: a Thymeleaf site plus a mobile API

Your company has a server-rendered Thymeleaf site with session login, plus a mobile-app API under /api/** that uses OAuth2 bearer tokens. Describe the security configuration for CSRF.

Answer

Use two SecurityFilterChain beans. The /api/** chain, ordered first with securityMatcher("/api/**"), is a stateless resource server with CSRF disabled, because mobile clients send tokens in the Authorization header and nothing is automatic. The default chain keeps CSRF enabled with the default session-backed repository; Thymeleaf injects the masked _csrf hidden field into every form, so no extra code is needed. Session cookies get Secure, HttpOnly and SameSite=Lax. The reasoning: CSRF exposure is decided per credential transport, so the decision belongs per chain, not globally. Ordering is covered in security filter chain.

More in Spring Boot

read ✓Spring Boot · hard

Spring Actuator Exposure and Operational Access

Which Spring Boot Actuator endpoints to expose, how exposure differs from authorization, and how to lock down env, heapdump and health details.

~7 min readread →
esc