认识CSRF攻击

什么是 CSRF

在之前，我们配置 SecurityConfig 的时候，一直有一个配置就是 .csrf()，回忆一下之前使用 Spring Security 默认页登录的时候，该配置 Spring Security 默认开启，主要做用于 CSRF 防护

CSRF（Cross-Site Request Forgery ，也就是跨站请求伪造），也可称为一键式攻击（one-click-attack）或 Session Riding（会话劫持），通常缩写为 CSRF 或者 XSRF。

CSRF 攻击是一种挟持用户在当前已登录的浏览器上发送恶意请求的攻击方法。

相对于 xss 利用用户对指定网站的信任，CSRD 则是利用网站对用户网页浏览器的信任。简单总结：XSS 是 “偷” 你的信息，CSRF 是 “借” 你的身份去做事。

它是一种常见的网络攻击手段，攻击者诱导用户在已登录目标网站的状态下，去访问一个恶意网站或点击恶意链接，从而在用户不知情的情况下，以用户的身份向目标网站发送伪造的请求，执行攻击者预设的操作。

什么意思，那些 Steam 各种骗子，伪装成一个你看不出来的官方的身份，给你发了一个看似官方的欺骗性地址，你在里面登录了，你 Steam 号就没了

攻击者盗用了你的身份，以你的名义做了某件事（比如转账、改密码、发帖子），而目标网站会误以为这个请求是你主动发起的。

在这里说一下同站与跨站的判定：浏览器的 “同站” 判定是基于注册域名 + 端口，而非子域名。

CSRF 攻击原理

要理解 CSRF 的原理，首先要明白 HTTP 会话认证机制 的特点

绝大多数网站是基于 Cookie 来维持用户登录状态的。当用户登录网站后，网站会在用户浏览器中种下一个包含身份信息的 Cookie，后续用户向该网站发送的所有请求，浏览器都会自动携带这个 Cookie，网站通过验证 Cookie 来确认用户身份。

CSRF 攻击正是利用了 浏览器自动携带 Cookie 这个特性，其攻击流程可以分为 4 步：

  1. 用户登录可信网站 A

    用户在浏览器中登录了目标网站 A（比如网上银行、电商平台），网站 A 在用户浏览器中种下了登录状态的 Cookie，此时用户处于已认证状态

  2. 用户未退出网站 A，访问恶意网站 B

    用户没有退出网站 A，就打开了一个新标签页，访问了攻击者搭建的恶意网站 B。

  3. 恶意网站 B 发送伪造请求到网站 A

    恶意网站 B 的页面中，隐藏了一段代码（比如<img>标签、<form>表单、JavaScript 脚本），这段代码会自动向网站 A 的某个接口发送请求（比如转账接口、修改个人信息接口）。

    例如：

    1
    2
    <!-- 恶意网站B中的隐藏代码，伪造转账请求 -->
    <img src="https://www.网站A.com/transfer?to=攻击者账户&amount=1000" style="display:none;">

  4. 浏览器自动携带 Cookie，网站 A 执行请求

    当浏览器加载这段代码时，会向网站 A 发送转账请求，并且自动携带网站 A 的登录 Cookie

    网站 A 收到请求后，验证 Cookie 发现用户是已登录状态，就会认为这个请求是用户主动发起的，进而执行转账操作。

img****

整个过程中，用户完全不知情，攻击就已经完成了。

那么，整个流程中，CSRF 攻击的关键前提是什么

  1. 用户必须已登录目标网站 A

    如果用户没有登录网站 A，浏览器中没有网站 A 的登录 Cookie，那么伪造的请求会因为身份验证失败而被拒绝。

  2. 目标网站的接口是 “不安全的”

    目标网站的接口只验证了用户的登录状态（Cookie），但没有验证请求是否是用户主动发起的

  3. 用户需要被诱导访问恶意网站

    攻击者需要通过钓鱼邮件、恶意链接、论坛广告等方式，诱导用户在登录状态下访问恶意页面。

防御 CSRF 是思路是什么

常见的防御手段有以下几种：

  1. 添加 CSRF Token

    这是最主流、最有效的防御方式。也是 Spring Security 的默认防御模式

    • 网站在生成页面时，会给每个用户生成一个唯一的 CSRF Token（随机字符串），并将 Token 存储在 Session 中，同时在页面的表单或请求头中嵌入这个 Token。
    • 当用户发送请求时，需要同时携带这个 Token，网站会验证请求中的 Token 和 Session 中的 Token 是否一致。
    • 攻击者无法获取用户的 CSRF Token，因此伪造的请求会因为缺少有效 Token 而被拒绝。

  2. 验证请求的 Referer/Origin 头

    • Referer 头：记录了请求的来源页面地址，网站可以检查 Referer 是否为自己的域名，如果不是则拒绝请求。
    • Origin 头：比 Referer 更安全，只包含域名，不包含具体路径，避免了 Referer 可能被篡改的风险。
    • 缺点：部分浏览器可能会因为隐私设置不发送 Referer 头。

  3. 使用 SameSite Cookie 属性

    • 给 Cookie 设置 SameSite 属性，限制 Cookie 的跨站发送：
      • SameSite=Strict：Cookie 仅在同站请求中携带，跨站请求绝对不携带。
      • SameSite=Lax：允许部分安全的跨站请求携带 Cookie（比如 GET 请求），禁止 POST 等敏感请求。

  4. 要求敏感操作输入验证码 / 密码

    对于转账、改密码等高危操作，强制要求用户输入验证码或密码，即使请求被伪造，也因为缺少验证码而无法执行。

  5. 2FA

    最牛逼最先进最可靠的方式，伟大，无需多言

虽然 CSRF 保护很重要，但在以下情况下，我们在开发的时候通常会选择禁用它http.csrf(csrf -> csrf.disable());：

  1. 无状态服务（纯 JWT）：如果你完全不使用 Cookie 进行身份验证（而是使用 Authorization: Bearer <JWT>），那么 CSRF 攻击就无法实现，因为浏览器不会自动在 Header 中带上 JWT。
  2. 非浏览器客户端：如果你的 API 只提供给移动 App 或其他服务器调用。

Spring Security 如何防御 CSRF

同步令牌模式

Spring Security 主要采用 同步令牌模式（Synchronizer Token Pattern） 来防御 CSRF，而且它也是Spring Security 的默认方案

服务器在渲染每个需要保护的表单页面时，向用户 Session 中存入一个随机生成的 Token，并在表单中以隐藏字段输出

提交时，服务器验证该字段与 Session 中的 Token 是否一致，若不匹配则拒绝请求。此模式能有效防止 CSRF 攻击，因为攻击者无法从第三方域读取到该随机 Token。

img
  • 生成令牌：当用户访问页面时，服务器生成一个随机的 CSRF Token，并将其存入服务器会话（Session）或 Cookie 中。
  • 注入令牌：服务器在返回的 HTML 表单中嵌入一个隐藏字段，或者要求前端从 Cookie 中读取并放入 HTTP Header。
  • 校验令牌：当用户提交 POST/PUT/DELETE 等修改数据的请求时，Spring Security 的 CsrfFilter 会拦截请求，对比请求中的 Token 与服务器保存的 Token 是否一致。
  • 拒绝非法请求：如果 Token 缺失或不匹配，服务器直接返回 403 Forbidden。

那么，这个额外的 CSRF Token 如何存储

  • 基于 Session 的存储（默认）
    • 组件：HttpSessionCsrfTokenRepository
    • 特点：Token 存在服务器 Session 中。安全性最高，但要求后端是有状态的。
    • 适用场景：传统的 Thymeleaf/JSP 模板引擎应用。
  • 基于 Cookie 的存储
    • 组件：CookieCsrfTokenRepository
    • 特点：后端不存 Session，而是把 Token 写入一个名为 XSRF-TOKEN 的 Cookie 中。
    • 适用场景：前后端分离（SPA，如 React/Vue）。
    • 实现细节：前端读取该 Cookie，并在发送 AJAX 请求时将其放入 Header（通常名为 X-XSRF-TOKEN）。

它是 CSRF Token 防御的一种变体，核心思路是：

  • 生成 CSRF Token 并写入 Cookie

    和上面一样，这个 Cookie 是可跨站携带的，但是 Token 本身是唯一的

  • 前端请求时携带 Token

    前端在发送非 GET 的敏感请求（POST/PUT/DELETE 等）时，需要将 Cookie 中的 CSRF Token 同时携带在请求参数、请求头或表单字段中。

  • 服务器验证 Token 一致性

    服务器收到请求后，会同时提取Cookie 中的 CSRF Token和请求中携带的 CSRF Token，对比两者是否一致：

    • 一致：说明是用户主动发起的请求，允许执行；
    • 不一致 / 缺失：判定为 CSRF 攻击，拒绝请求。

CSRF 攻击的核心是攻击者能诱导浏览器自动携带 Cookie，但无法读取 Cookie 中的内容（浏览器的同源策略限制：跨域网站无法读取其他域名的 Cookie）

因此：

  • 攻击者可以诱导用户发送请求（浏览器自动带 Cookie 里的 Token），但无法获取 Cookie 中的 Token，也就无法将其添加到请求参数 / 头中；
  • 服务器验证时，因为请求中没有对应的 Token，会直接拒绝，从而防御攻击。

双重提交 Cookie 是另一种配置方式，不需要服务器存储 Token，下面使用到的时候会说

sequenceDiagram
    participant User
    participant Browser
    participant Server (Spring Security)

    User->>Browser: 首次访问后端网站（如http://localhost:8080）
    Browser->>Server: 发送GET请求
    Server->>Server: 生成CSRF Token（如：abc123）
    Server->>Browser: 响应并写入Cookie：XSRF-TOKEN=abc123
    Browser->>User: 加载页面

    User->>Browser: 点击按钮发送POST请求（如/api/hello）
    Browser->>Browser: 读取Cookie中的XSRF-TOKEN=abc123，添加到请求头X-XSRF-TOKEN=abc123
    Browser->>Server: 发送POST请求（携带Cookie：XSRF-TOKEN=abc123 + 请求头：X-XSRF-TOKEN=abc123）
    Server->>Server: 提取两个Token并对比，一致则通过验证
    Server->>Browser: 执行请求并返回响应
    Browser->>User: 展示响应结果

    Note over Browser,Server: CSRF攻击场景：攻击者诱导用户发送请求，但无法读取Cookie中的Token，请求头中无X-XSRF-TOKEN，服务器拒绝请求

双重提交 Cookie的核心是将 CSRF Token 同时放在 Cookie 和请求中，服务器验证两者一致性，利用浏览器同源策略限制攻击者读取 Cookie，从而防御 CSRF；

SameSite是 Cookie 的一个属性（RFC 6265bis 标准），它的核心作用是限制 Cookie 在跨站请求中的发送行为，从而从根源上阻断 CSRF 攻击的关键环节（因为浏览器自动携带跨站请求的 Cookie）。

这个属性可以告诉浏览器：什么样的跨站请求中，我才允许携带这个 Cookie？

SameSite 的三个核心取值

取值 行为说明 对 CSRF 的防御效果
SameSite=Strict（严格模式） 仅在同站请求中携带 Cookie。所谓 “同站”，是指域名 + 端口完全一致（比如https://www.example.com和https://blog.example.com不算同站，因为子域名不同）；跨站请求（比如从https://malicious.com请求https://example.com）绝对不会携带 Cookie。 防御效果最强，几乎能阻断所有 CSRF 攻击
SameSite=Lax（宽松模式，浏览器默认值） 允许部分安全的跨站 GET 请求携带 Cookie，禁止 POST/PUT/DELETE 等敏感请求携带 Cookie。允许的场景：链接跳转（<a href>）、预加载（<link rel="prefetch">）、表单 GET 提交（<form method="get">）；禁止的场景：AJAX POST 请求、表单 POST 提交、<img>/<script>的跨站请求。 能防御绝大多数 CSRF 攻击（因为 CSRF 攻击常用 POST 等敏感请求），同时兼顾用户体验
SameSite=None（无限制） 允许所有跨站请求携带 Cookie，但必须同时设置Secure属性（即 Cookie 只能通过 HTTPS 传输）。适用于需要跨站携带 Cookie 的场景（比如第三方登录、跨域支付）。 无 CSRF 防御效果，需要配合其他防御手段（如 CSRF Token）

在 Spring 生态中，配置 Cookie 的SameSite属性分两种场景：普通 Cookie和Spring Security 生成的 Cookie（如 JSESSIONID、XSRF-TOKEN）。

如果是你自己在代码中生成的 Cookie（比如用户信息 Cookie），可以直接通过Cookie对象的setSameSite方法配置：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
import jakarta.servlet.http.Cookie;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class CookieController {

    @GetMapping("/set-cookie")
    public String setCookie(HttpServletResponse response) {
        Cookie cookie = new Cookie("user_info", "user123");
        cookie.setPath("/");
        cookie.setMaxAge(3600); // 有效期1小时
        // 配置SameSite属性为Lax（常用）
        cookie.setSameSite("Lax");
        // 如果是SameSite=None，必须设置Secure（仅HTTPS传输）
        // cookie.setSameSite("None");
        // cookie.setSecure(true);
        // 可选：设置HttpOnly，防止XSS窃取Cookie
        cookie.setHttpOnly(true);
        response.addCookie(cookie);
        return "Cookie已设置，SameSite=Lax";
    }
}

那么，如何配置 Spring Security 生成的 Cookie 呢？这个下面说

在实际项目中，我们通常会同时使用 SameSite Cookie 和双重提交 Cookie，形成 “双层防护”，原因如下：

  • SameSite=Lax/Strict虽然能防御大部分 CSRF 攻击，但存在兼容性问题：部分老旧浏览器（如 IE）不支持SameSite属性，此时攻击仍可能发生；
  • SameSite=None需要开启Secure（仅 HTTPS），如果项目在测试环境使用 HTTP，就无法使用；说实话很少特意去配置 None
  • 双重提交 Cookie 可以作为兜底方案，即使SameSite失效，仍能防御 CSRF。
sequenceDiagram
    participant Attacker
    participant User
    participant Browser
    participant Server

    Note over Attacker,Server: CSRF攻击场景
    Attacker->>User: 诱导点击恶意链接（跨站POST请求到目标网站）
    User->>Browser: 点击链接（已登录目标网站）
    Browser->>Browser: 检查目标网站Cookie的SameSite属性
    alt SameSite=Strict/Lax
        Browser->>Browser: 跨站POST请求不携带Cookie
        Browser->>Server: 发送POST请求（无Cookie）
        Server->>Browser: 身份验证失败，拒绝请求
    else SameSite=None（或浏览器不支持）
        Browser->>Browser: 携带Cookie，但前端无XSRF-TOKEN（攻击者无法读取）
        Browser->>Server: 发送POST请求（有Cookie，无X-XSRF-TOKEN头）
        Server->>Browser: 双重提交Cookie验证失败，拒绝请求
    end
    Browser->>User: 请求失败，攻击被阻断

Spring Security 中 CSRF 防御实践

同步令牌模式

Spring Security 默认开启 CSRF 保护，采用的是同步令牌模式

基于 Session 的存储

由于这个我没有前后端一体的代码，只能简单说说了

服务器为每个用户的 Session 生成唯一的 CSRF Token，存储在服务器端的 Session 中，同时将 Token 嵌入到前端页面，然后

Spring Security 默认的 CSRF 防护会自动为每个 Session 生成 CSRF Token，存储在HttpSession中，所以，不需要额外配置

默认情况下，CSRF 防护会拦截非 GET/HEAD/OPTIONS/TRACE的请求（如 POST/PUT/DELETE），要求携带 CSRF Token。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
package com.example.csrfsessiondemo.controller;

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.*;

@Controller
public class CsrfDemoController {

    // 首页跳转（Thymeleaf页面）
    @GetMapping("/")
    public String index() {
        return "index"; // 对应resources/templates/index.html
    }

    // 处理POST请求（需要CSRF Token）
    @PostMapping("/api/hello")
    @ResponseBody
    public String helloPost(@RequestParam String message) {
        return "成功接收POST请求：" + message;
    }

    // 处理PUT请求（需要CSRF Token）
    @PutMapping("/api/update")
    @ResponseBody
    public String updatePut(@RequestParam String data) {
        return "成功接收PUT请求：" + data;
    }
}

使用 Thymeleaf 渲染页面，演示两种常见的 Token 携带方式：表单提交和AJAX 请求。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org"
      xmlns:sec="http://www.thymeleaf.org/extras/spring-security">
<head>
    <meta charset="UTF-8">
    <title>CSRF Session Token Demo</title>
</head>
<body>
    <h1>CSRF 同步令牌模式（基于Session）演示</h1>

    <!-- 显示当前登录用户 -->
    <div sec:authorize="isAuthenticated()">
        <p>当前用户：<span sec:authentication="name"></span></p>
        <a href="/logout">退出登录</a>
    </div>

    <hr>

    <!-- 方式1：表单提交（自动携带CSRF Token） -->
    <h3>方式1：表单POST提交</h3>
    <form action="/api/hello" method="post">
        <!-- Thymeleaf的Spring Security标签会自动生成CSRF Token的隐藏域 -->
        <!-- 等价于：<input type="hidden" name="_csrf" th:value="${_csrf.token}" /> -->
        <input type="hidden" th:name="${_csrf.parameterName}" th:value="${_csrf.token}" />
        <input type="text" name="message" placeholder="请输入消息" value="Hello CSRF">
        <button type="submit">提交表单</button>
    </form>

    <hr>

    <!-- 方式2：AJAX POST请求（手动携带CSRF Token到请求头/参数） -->
    <h3>方式2：AJAX POST请求</h3>
    <input type="text" id="ajaxMessage" placeholder="请输入消息" value="Hello AJAX">
    <button onclick="sendAjaxPost()">发送AJAX POST</button>
    <p id="ajaxResult"></p>

    <hr>

    <!-- 方式3：AJAX PUT请求（手动携带CSRF Token） -->
    <h3>方式3：AJAX PUT请求</h3>
    <input type="text" id="ajaxData" placeholder="请输入更新数据" value="Update Data">
    <button onclick="sendAjaxPut()">发送AJAX PUT</button>
    <p id="putResult"></p>

    <!-- JS代码：获取CSRF Token并发送AJAX请求 -->
    <script>
        // 1. 获取CSRF Token（从页面的meta标签或隐藏域中获取，这里用Thymeleaf注入）
        const csrfToken = /*[[${_csrf.token}]]*/ '';
        const csrfHeader = /*[[${_csrf.headerName}]]*/ ''; // 默认是X-CSRF-TOKEN

        // 2. 发送AJAX POST请求（携带Token到请求头）
        function sendAjaxPost() {
            const message = document.getElementById('ajaxMessage').value;
            fetch('/api/hello', {
                method: 'POST',
                headers: {
                    'Content-Type': 'application/x-www-form-urlencoded',
                    [csrfHeader]: csrfToken // 关键：请求头中携带CSRF Token
                },
                body: 'message=' + encodeURIComponent(message)
            })
            .then(response => response.text())
            .then(data => {
                document.getElementById('ajaxResult').innerText = data;
            })
            .catch(error => {
                document.getElementById('ajaxResult').innerText = '请求失败：' + error;
            });
        }

        // 3. 发送AJAX PUT请求（携带Token到请求参数）
        function sendAjaxPut() {
            const data = document.getElementById('ajaxData').value;
            fetch('/api/update?_csrf=' + csrfToken, { // 关键：请求参数中携带CSRF Token
                method: 'PUT',
                headers: {
                    'Content-Type': 'application/x-www-form-urlencoded'
                },
                body: 'data=' + encodeURIComponent(data)
            })
            .then(response => response.text())
            .then(data => {
                document.getElementById('putResult').innerText = data;
            })
            .catch(error => {
                document.getElementById('putResult').innerText = '请求失败：' + error;
            });
        }
    </script>
</body>
</html>
  • Thymeleaf 注入 Token：Spring Security 会将 CSRF Token 封装在模型变量_csrf中，包含token（令牌值）、parameterName（默认是_csrf）、headerName（默认是X-CSRF-TOKEN）。
  • 表单提交：通过隐藏域<input type="hidden" name="_csrf" th:value="${_csrf.token}" />携带 Token，这是最基础的方式。
  • AJAX 请求：可以将 Token 放在请求头（X-CSRF-TOKEN）或请求参数（_csrf）中，Spring Security 都能识别。

首先，我们应该自己实现一个基于 Cookie 的存储的仓库，官方提供的基于 Cookie 存储 CSRF Token 的接口如下

image-20251221143708997

如果你不自己实现，注意 SecurityConfig 中相关的内容的填写

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
@Configuration
@EnableWebSecurity
public class SecurityConfig {

    /**
     * 配置 CSRF 令牌存储为 Cookie 模式
     * CookieCsrfTokenRepository 会做两件事：
     * 1. 生成 CSRF 令牌，存储到名为 XSRF-TOKEN 的 Cookie 中（前端可读取）
     * 2. 期望客户端通过 X-XSRF-TOKEN 请求头携带令牌回服务器
     */
    @Bean
    public CsrfTokenRepository csrfTokenRepository() {
        CookieCsrfTokenRepository repository = CookieCsrfTokenRepository.withHttpOnlyFalse();
        // 自定义 Cookie 名称（可选，默认是 XSRF-TOKEN）
        repository.setCookieName("MY-XSRF-TOKEN");
        // 自定义请求头名称（可选，默认是 X-XSRF-TOKEN）
        repository.setHeaderName("MY-X-XSRF-TOKEN");
        // 设置 Cookie 的路径（可选，默认是 /）
        repository.setCookiePath("/");
        return repository;
    }

    /**
     * 配置 Security 过滤链
     */
    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
                // 授权配置：所有请求都需要认证（方便测试，也可以配置为部分请求）
                .authorizeHttpRequests(auth -> auth.anyRequest().authenticated())
                // 开启表单登录（默认的登录页面，方便测试）
                .formLogin(form -> form.permitAll())
                // 开启 CSRF 保护，并指定令牌存储方式为 Cookie
                .csrf(csrf -> csrf.csrfTokenRepository(csrfTokenRepository()));

        return http.build();
    }
}

随便挑了一个接口进行测试，你会发现

image-20251221144527966

Cookie 中多了一个名为 MY-XSRF-TOKEN 的 Cookie，其值就是 CSRF 令牌

因为这个请求是 POST，我没携带 Token，所以我这边就是 401

在 Spring Security 中，双重提交 Cookie（Double Submit Cookie） 是一种常用的无状态 CSRF 防御机制，非常适合前后端分离的项目。

服务器生成一个随机 Token 写入 Cookie，前端在发送 POST/PUT 等写操作请求时，从 Cookie 中读取该 Token 并放入自定义 HTTP Header（如 X-XSRF-TOKEN）中。后端拦截器比对 Cookie 中的值与 Header 中的值，一致则放行。

所以说，需要配置Security 配置，而且关键在于配置 CookieCsrfTokenRepository。为了让前端 JavaScript 能够读取 Cookie，必须设置 withHttpOnlyFalse()。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.web.SecurityFilterChain;
import org.springframework.security.web.csrf.CookieCsrfTokenRepository;
import org.springframework.security.web.csrf.CsrfTokenRequestAttributeHandler;

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        // 配置 CSRF 处理器，用于处理延迟生成的 Token
        CsrfTokenRequestAttributeHandler requestHandler = new CsrfTokenRequestAttributeHandler();
        // 设置注入属性名（默认为 _csrf），用于前端或 Filter 获取
        requestHandler.setCsrfRequestAttributeName(null);

        http
            .csrf(csrf -> csrf
                .csrfTokenRepository(CookieCsrfTokenRepository.withHttpOnlyFalse()) // 允许 JS 读取 Cookie
                .csrfTokenRequestHandler(requestHandler)
            )
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/api/public/**").permitAll()
                .anyRequest().authenticated()
            )
		   .addFilterAfter(new CsrfCookieFilter(), BasicAuthenticationFilter.class);
        return http.build();
    }
}

而在 Spring Security 6 中，CSRF Token 默认是延迟加载的。为了确保前端在第一次访问时就能拿到 Cookie，我们需要一个 Filter 或 Controller 来显式触发它。而且别忘了在 Security中的配置器链中加入这个自己的过滤器

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.security.web.csrf.CsrfToken;
import org.springframework.web.filter.OncePerRequestFilter;
import java.io.IOException;

/**
 * 这个 Filter 确保每个请求都会将 CSRF Token 写入 Cookie
 */
public class CsrfCookieFilter extends OncePerRequestFilter {
    @Override
    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain)
            throws ServletException, IOException {
        CsrfToken csrfToken = (CsrfToken) request.getAttribute(CsrfToken.class.getName());
        if (csrfToken != null) {
            // 显式触发 Token 的生成，从而让 CookieCsrfTokenRepository 将其写入响应 Cookie
            csrfToken.getToken();
        }
        filterChain.doFilter(request, response);
    }
}

当前端发起请求时，库会自动处理双重提交逻辑。

  1. 读取 Cookie：前端获取名为 XSRF-TOKEN 的 Cookie 值。
  2. 设置 Header：在请求头中加入 X-XSRF-TOKEN。

而Axios 默认就支持这一机制，只需全局配置一下：

1
2
3
4
5
6
7
8
9
10
11
import axios from 'axios';

// 配置 Axios 自动读取 Cookie 并设置 Header
axios.defaults.xsrfCookieName = 'XSRF-TOKEN';
axios.defaults.xsrfHeaderName = 'X-XSRF-TOKEN';
axios.defaults.withCredentials = true; // 确保跨域请求也带上 Cookie

// 发送 POST 请求
axios.post('/api/data', { name: 'ErgouTree' })
    .then(res => console.log(res))
    .catch(err => console.error(err));

我这边手上没有一个使用这样的前端例子，所以说，测试的时候就使用浏览器访问后端一个 GET 接口。查看浏览器控制台 Application -> Cookies，你会发现一个 XSRF-TOKEN。

使用 Postman 或前端代码发送 POST 请求，并在 Header 中带上：

  • Cookie: XSRF-TOKEN=你的值
  • X-XSRF-TOKEN: 你的值

结果：返回 200 OK。

注意，使用这种方式，在生产环境中，请务必使用 CookieCsrfTokenRepository.withHttpOnlyFalse().setSecure(true)。如果不用 HTTPS，Token 容易被中间人窃取。

使用 SameSite 属性，就是告诉浏览器，在跨站请求时，是否允许发送该 Cookie。

在 Spring 生态中，配置 Spring Security 生成的 Cookie（JSESSIONID 和 XSRF-TOKEN）主要通过以下两种方式：

  • 配置 Session Cookie—JSESSIONID

    JSESSIONID 是由 Servlet 容器（如 Tomcat）或 Spring Session 管理的。

    • 如果你没有使用 Spring Session，可以直接在 application.properties 中配置：

      1
      2
      3
      4
      5
      6
      # 设置为 Strict（最严格）或 Lax（推荐，兼顾体验与安全）
      server.servlet.session.cookie.same-site=lax
      # 建议同时开启，确保只在 HTTPS 下传输
      server.servlet.session.cookie.secure=true
      # 增强安全性，防止 JS 读取 Session ID
      server.servlet.session.cookie.http-only=true

    • 如果你使用了 Spring Session（例如存储在 Redis 中），则需要配置一个 CookieSerializer 的 Bean，来配置其中的 SameSite 属性

      1
      2
      3
      4
      5
      6
      7
      8
      9
      @Bean
      public DefaultCookieSerializer cookieSerializer() {
          DefaultCookieSerializer serializer = new DefaultCookieSerializer();
          serializer.setCookieName("JSESSIONID");
          serializer.setCookiePath("/");
          // 配置 SameSite
          serializer.setSameSite("Lax"); 
          return serializer;
      }

      这样就修改了

  • 配置 CSRF Cookie ——XSRF-TOKEN

    这个 Token 是 Spring Security 在你开启相关 CSRF 设置之后专门生成的

    image-20251221150528258

    所以，我们可以自定义 CSRF Token 存储库，来为 Spring Security 中的 Token 设置 samesite 属性

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    @Configuration
    @EnableWebSecurity
    public class SecurityConfig {

        @Bean
        public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
            http
                .csrf(csrf -> csrf
                    .csrfTokenRepository(cookieCsrfTokenRepository())
                    // 同样需要这个处理器来确保前端能获取 Token
                    .csrfTokenRequestHandler(new CsrfTokenRequestAttributeHandler())
                )
                .authorizeHttpRequests(auth -> auth.anyRequest().authenticated());

            return http.build();
        }

        /**
         * 自定义 CSRF Token 存储库
         */
        private CookieCsrfTokenRepository cookieCsrfTokenRepository() {
            CookieCsrfTokenRepository repository = CookieCsrfTokenRepository.withHttpOnlyFalse();
            
            // 关键点：通过 Customizer 设置 SameSite 属性
            repository.setCookieCustomizer(cookieBuilder -> {
                cookieBuilder.sameSite("Lax"); // 设置为 Lax 或 Strict
                // cookieBuilder.secure(true); // 生产环境务必开启
            });
            
            return repository;
        }
    }

这个 samesite 其实是默认开启的，通常情况下，保持默认的 Lax 基本不会有问题，Strict 可能在重定向的时候失去登陆状态，而且 OAuth2 部分兼容存在问题