Spring Security CSRF Protection: Tokens, Thymeleaf, SPAs, REST APIs and Common 403 Errors

<!-- Hosted on evil.com: the browser will attach bank.com cookies when this submits -->
<form id="attack" action="https://bank.com/transfer" method="POST">
    <input type="hidden" name="amount" value="10000">
    <input type="hidden" name="to" value="attacker">
</form>
<script>
    document.getElementById('attack').submit();   // runs as soon as the victim opens the page
</script>

# application.yml
server:
  servlet:
    session:
      cookie:
        same-site: lax        # explicit SameSite for the session cookie
        secure: true          # send only over HTTPS
        http-only: true       # not readable by JavaScript

@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
    http
        .csrf(Customizer.withDefaults())      // same as not configuring CSRF at all
        .authorizeHttpRequests(auth -> auth.anyRequest().authenticated())
        .formLogin(Customizer.withDefaults());
    return http.build();
}

// Handy for JSON clients and tests: an endpoint that hands out the current token.
// Spring resolves the CsrfToken method argument from the request.
@RestController
public class CsrfController {

    @GetMapping("/csrf")
    public CsrfToken csrf(CsrfToken token) {
        return token;   // JSON: parameterName, headerName, token
    }
}

# 1. Fetch the current token (also sets the session cookie):
curl -s -c jar.txt -b jar.txt http://localhost:8080/csrf
# {"parameterName":"_csrf","headerName":"X-CSRF-TOKEN","token":"k3J..."}

# 2. POST without the token: rejected
curl -i -b jar.txt -X POST http://localhost:8080/users \
     -H "Content-Type: application/json" -d '{"name":"Alice"}'
# HTTP/1.1 403

# 3. POST with the token in the header: accepted
curl -i -b jar.txt -X POST http://localhost:8080/users \
     -H "Content-Type: application/json" \
     -H "X-CSRF-TOKEN: k3J..." \
     -d '{"name":"Alice"}'
# HTTP/1.1 201

<!-- 1. th:action adds the hidden _csrf field automatically -->
<form th:action="@{/users}" method="post">
    <input type="text" name="name" />
    <input type="email" name="email" />
    <button type="submit">Create User</button>
</form>

<!-- 2. Plain action attribute: add the token yourself -->
<form action="/users" method="post">
    <input type="hidden" th:name="${_csrf.parameterName}" th:value="${_csrf.token}" />
    <input type="text" name="name" />
    <button type="submit">Create User</button>
</form>

<!-- 3. Logout must be a POST with a token -->
<form th:action="@{/logout}" method="post">
    <button type="submit">Log out</button>
</form>

<!-- 4. AJAX from a Thymeleaf page: expose the token in the head -->
<head>
    <meta name="_csrf" th:content="${_csrf.token}" />
    <meta name="_csrf_header" th:content="${_csrf.headerName}" />
</head>

<script>
    const token  = document.querySelector('meta[name="_csrf"]').content;
    const header = document.querySelector('meta[name="_csrf_header"]').content;

    fetch('/users', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            [header]: token                   // X-CSRF-TOKEN: <token>
        },
        body: JSON.stringify({ name: 'Alice' })
    });
</script>

// Simple version: raw token accepted, eager loading so the cookie is always written
@Bean
public SecurityFilterChain spaChain(HttpSecurity http) throws Exception {
    CsrfTokenRequestAttributeHandler requestHandler = new CsrfTokenRequestAttributeHandler();
    requestHandler.setCsrfRequestAttributeName(null);   // load the token eagerly

    http
        .csrf(csrf -> csrf
            .csrfTokenRepository(CookieCsrfTokenRepository.withHttpOnlyFalse())
            .csrfTokenRequestHandler(requestHandler))
        .authorizeHttpRequests(auth -> auth.anyRequest().authenticated());
    return http.build();
}

@Bean
public SecurityFilterChain spaChain(HttpSecurity http) throws Exception {
    http
        .csrf(csrf -> csrf
            .csrfTokenRepository(CookieCsrfTokenRepository.withHttpOnlyFalse())
            .csrfTokenRequestHandler(new SpaCsrfTokenRequestHandler()))
        .addFilterAfter(new CsrfCookieFilter(), BasicAuthenticationFilter.class)
        .authorizeHttpRequests(auth -> auth.anyRequest().authenticated());
    return http.build();
}

final class SpaCsrfTokenRequestHandler implements CsrfTokenRequestHandler {

    private final CsrfTokenRequestHandler plain = new CsrfTokenRequestAttributeHandler();
    private final CsrfTokenRequestHandler xor = new XorCsrfTokenRequestAttributeHandler();

    @Override
    public void handle(HttpServletRequest request, HttpServletResponse response,
                       Supplier<CsrfToken> csrfToken) {
        xor.handle(request, response, csrfToken);   // keeps masking for tokens rendered in pages
    }

    @Override
    public String resolveCsrfTokenValue(HttpServletRequest request, CsrfToken csrfToken) {
        String headerValue = request.getHeader(csrfToken.getHeaderName());
        return (StringUtils.hasText(headerValue) ? plain : xor)
            .resolveCsrfTokenValue(request, csrfToken);   // raw from header, masked from forms
    }
}

final class CsrfCookieFilter extends OncePerRequestFilter {

    @Override
    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response,
                                    FilterChain chain) throws ServletException, IOException {
        CsrfToken token = (CsrfToken) request.getAttribute("_csrf");
        if (token != null) {
            token.getToken();   // reading the token makes Spring write the cookie
        }
        chain.doFilter(request, response);
    }
}

function getCookie(name) {
    const match = document.cookie.match(new RegExp('(?:^|; )' + name + '=([^;]*)'));
    return match ? decodeURIComponent(match[1]) : null;
}

async function createUser(user) {
    const response = await fetch('/api/users', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'X-XSRF-TOKEN': getCookie('XSRF-TOKEN')    // read again after login: the token changes
        },
        credentials: 'same-origin',                    // sends the session cookie
        body: JSON.stringify(user)
    });
    if (response.status === 403) {
        throw new Error('CSRF token missing or invalid');
    }
    return response.json();
}

@Bean
public SecurityFilterChain apiFilterChain(HttpSecurity http) throws Exception {
    http
        .csrf(csrf -> csrf.disable())                  // OK: auth is a Bearer header, not a cookie
        .sessionManagement(session -> session
            .sessionCreationPolicy(SessionCreationPolicy.STATELESS))
        .authorizeHttpRequests(auth -> auth.anyRequest().authenticated());
    return http.build();
}

@Bean
public SecurityFilterChain mixedFilterChain(HttpSecurity http) throws Exception {
    http
        .csrf(csrf -> csrf
            .ignoringRequestMatchers(
                "/api/**",                        // bearer-token API: no cookie auth
                "/webhooks/stripe"))              // verified by signature instead
        .authorizeHttpRequests(auth -> auth
            .requestMatchers("/webhooks/**").permitAll()   // access control is the signature check
            .anyRequest().authenticated())
        .formLogin(Customizer.withDefaults());
    return http.build();
}

@Component
public class CsrfAwareAccessDeniedHandler implements AccessDeniedHandler {

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

    private final AccessDeniedHandler fallback = new AccessDeniedHandlerImpl();
    private final ObjectMapper mapper;

    public CsrfAwareAccessDeniedHandler(ObjectMapper mapper) {
        this.mapper = mapper;
    }

    @Override
    public void handle(HttpServletRequest request, HttpServletResponse response,
                       AccessDeniedException ex) throws IOException, ServletException {
        if (ex instanceof CsrfException) {
            log.warn("CSRF rejection for {} {}: {}", request.getMethod(),
                     request.getRequestURI(), ex.getClass().getSimpleName());
            response.setStatus(HttpStatus.FORBIDDEN.value());
            response.setContentType(MediaType.APPLICATION_JSON_VALUE);
            mapper.writeValue(response.getOutputStream(), Map.of(
                "status", 403,
                "error", "csrf_token_invalid",
                "message", "The CSRF token is missing or invalid. Refresh and try again."));
        } else {
            fallback.handle(request, response, ex);
        }
    }
}

// In the filter chain:
// http.exceptionHandling(ex -> ex.accessDeniedHandler(csrfAwareAccessDeniedHandler));

@SpringBootTest
@AutoConfigureMockMvc
class CsrfProtectionTest {

    @Autowired
    MockMvc mockMvc;

    private static final String BODY = "{\"name\":\"Alice\"}";

    @Test
    void postWithoutTokenIsRejected() throws Exception {
        mockMvc.perform(post("/users")
                .with(user("alice"))
                .contentType(MediaType.APPLICATION_JSON).content(BODY))
            .andExpect(status().isForbidden());
    }

    @Test
    void postWithValidTokenIsAccepted() throws Exception {
        mockMvc.perform(post("/users")
                .with(user("alice"))
                .with(csrf())                               // adds a valid token (as a parameter)
                .contentType(MediaType.APPLICATION_JSON).content(BODY))
            .andExpect(status().isCreated());
    }

    @Test
    void tokenInHeaderIsAccepted() throws Exception {
        mockMvc.perform(post("/users")
                .with(user("alice"))
                .with(csrf().asHeader())                    // sent as X-CSRF-TOKEN
                .contentType(MediaType.APPLICATION_JSON).content(BODY))
            .andExpect(status().isCreated());
    }

    @Test
    void invalidTokenIsRejected() throws Exception {
        mockMvc.perform(post("/users")
                .with(user("alice"))
                .with(csrf().useInvalidToken())
                .contentType(MediaType.APPLICATION_JSON).content(BODY))
            .andExpect(status().isForbidden());
    }

    @Test
    void getRequestsNeedNoToken() throws Exception {
        mockMvc.perform(get("/users").with(user("alice")))
            .andExpect(status().isOk());
    }
}