Angular XSRF 防护指南：跨站请求伪造原理与 HttpClient 内置防御机制（developer-roadmap Angular 学习路线）

跨站请求伪造（XSRF/CSRF）是前端应用必须正视的高危漏洞：攻击者不窃取凭证，而是借受害浏览器对已登录站点的"自动携带会话 Cookie"特性，伪装用户身份发出恶意请求。本文基于 developer-roadmap 仓库的 XSRF Protection 主题文档，系统梳理 XSRF 的攻击原理、与钓鱼攻击的本质区别，并深入讲解 Angular HttpClient 内置的 XSRF 防护机制（Cookie 读取 Token、请求头回传、服务端校验的完整链路），同时结合仓库中 HttpClient CSRF、Cross-site Request Forgery 等相邻主题给出可落地的配置、测试与服务端配合方案。读完本文，你将能够准确识别 XSRF 攻击场景，并掌握在 Angular 应用中开启、自定义和验证 XSRF 防护的完整实战方法。

XSRF 是什么：一种"借刀杀人"的会话劫持攻击

跨站请求伪造（Cross-Site Request Forgery，简称 XSRF 或 CSRF）是一种恶意利用模式：攻击者诱骗用户的浏览器向用户已登录的可信站点发送未经授权的请求。

与钓鱼（Phishing）攻击有本质区别：

对比维度	钓鱼（Phishing）	XSRF/CSRF
攻击目标	窃取用户的账号凭证（用户名、密码等）	不窃取凭证，直接利用用户已激活的会话
攻击方式	欺骗用户主动交出敏感信息	让受害浏览器在用户无感知的情况下代为发请求
用户角色	受害者主动参与（输入信息）	受害者完全被动（浏览器自动执行）
核心利用点	人性与信任	浏览器自动携带 Cookie 的机制 + 会话有效性

这一区分正是 XSRF Protection 文档强调的重点：XSRF 不偷密码，它"借用"你已登录的会话。因此，即使攻击者完全不知道用户的任何凭证，只要用户的会话仍然有效，攻击就可能得逞。

攻击是如何发生的：自动携带 Cookie 的双刃剑

XSRF 攻击成立依赖两个前提：

1. 受害者已登录目标站点，浏览器中持有有效的会话 Cookie（如 sessionid、auth_token）。
2. 浏览器会为每个发往特定域名的请求自动附带该域名的 Cookie，无论这个请求是用户主动点击产生，还是来自恶意页面中隐藏的脚本。

典型攻击场景如下：

<!-- 恶意站点 attacker.example 上的隐藏内容 -->
<img src="https://bank.example/transfer?to=attacker&amount=10000" />

<form action="https://bank.example/change-password" method="POST" style="display:none">
  <input type="hidden" name="new_password" value="hacked123" />
  <input type="hidden" name="confirm_password" value="hacked123" />
</form>
<script>document.forms[0].submit();</script>

当受害者访问该恶意站点时，浏览器会向 bank.example 发起请求，并自动附带该域名的会话 Cookie。服务器校验会话通过后，便将这些请求视为用户本人的合法指令——转账、改密等操作被静默执行，用户数据与账户完整性因此受损。整个过程绕过了应用本应执行的验证步骤，这正是 Cross-site Request Forgery 主题文档描述的漏洞成因。

Angular 的防护思路：双提交 Cookie 模式

Angular 官方推荐的客户端防护方案基于**双提交 Cookie（Double Submit Cookie）**模式，这也是 XSRF Protection 文档所链接资源中专门讲解的模式：

1. 服务端在首次响应时生成一个随机安全 Token，写入 Cookie（Angular 默认约定 Cookie 名为 XSRF-TOKEN）。
2. **客户端（Angular HttpClient）**在发起后续请求时，自动读取该 Cookie 中的 Token，并把它放到自定义 HTTP 请求头中（Angular 默认约定请求头名为 X-XSRF-TOKEN）。
3. 服务端收到请求后，比对 Cookie 中的 Token 与请求头中的 Token 是否一致，从而确认请求确实来自本应用页面，而非第三方恶意站点。

这个模式之所以有效，依赖浏览器的同源策略：XSRF-TOKEN Cookie 是目标域名专属的，恶意站点（跨源）既无法读取该 Cookie 的内容，也无法为请求伪造出正确的 X-XSRF-TOKEN 请求头（设置自定义请求头会触发跨源预检请求，而预检请求本身不携带该 Cookie）。Token 相当于"只有同源页面才拿得到的暗号"。

需要强调的是，HttpClient CSRF 主题文档指出这套机制的核心流程正是：

启用该特性后，框架自动从 Cookie 读取 Token，并将其设置为后续请求的 HTTP 请求头；服务端随后校验该 Token，以确认请求来自预期应用而非恶意站点。

在 Angular 应用中启用 XSRF 防护

现代应用：provideHttpClient + withXsrfProtection

自 Angular 15 起，HttpClient 通过 provideHttpClient 函数以依赖注入方式提供。根据仓库中 Setting Up the Client 主题文档，多数应用在 app.config.ts 的 application providers 中完成配置：

import { provideHttpClient, withXsrfProtection } from '@angular/common/http';
import { ApplicationConfig } from '@angular/core';

export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(
      withXsrfProtection({
        cookieName: 'XSRF-TOKEN',   // 读取 Token 的 Cookie 名（默认值）
        headerName: 'X-XSRF-TOKEN', // 回传 Token 的请求头名（默认值）
      })
    ),
  ],
};

要点说明：

• 默认即安全：provideHttpClient() 默认就包含 XSRF 防护；只有当你想显式声明或修改默认值时，才需要调用 withXsrfProtection。
• 可自定义名称：如果服务端使用的 Cookie/请求头名称与 Angular 默认值不同（例如 Cookie 名为 csrftoken、请求头为 X-CSRFToken，常见于 Django 等后端框架），通过 cookieName 与 headerName 对齐即可，无需写任何拦截器代码。
• 依赖注入配置：仓库 Setting Up the Client 文档同时指出，如果应用仍采用 NgModule 引导方式，可在应用 NgModule 的 providers 中同样放入 provideHttpClient(...)。

传统应用：HttpClientXsrfModule

对于使用 NgModule 模块体系的旧式应用，Cross-site Request Forgery 主题文档专门引用了 HttpClientXsrfModule 这一官方 API：

import { HttpClientModule, HttpClientXsrfModule } from '@angular/common/http';
import { NgModule } from '@angular/core';

@NgModule({
  imports: [
    HttpClientModule,
    HttpClientXsrfModule.withOptions({
      cookieName: 'XSRF-TOKEN',
      headerName: 'X-XSRF-TOKEN',
    }),
  ],
})
export class AppModule {}

两种方式效果一致，选择取决于应用的引导风格：独立组件（standalone）时代推荐 withXsrfProtection，存量 NgModule 应用继续使用 HttpClientXsrfModule。

触发范围：写操作才是重点

XSRF 防护只对会改变服务端状态的方法（如 POST、PUT、DELETE、PATCH）有意义——攻击者真正能利用的也是这些"变更型"请求。GET/HEAD 等只读请求通常不携带 Token，这也是 Angular 内置拦截器默认不为只读请求附加该请求头的原因。在实际业务中，请确保转账、改密、删除、下单等写操作全部走 POST/PUT/DELETE，并把状态变更类接口纳入 XSRF 防护范围。

请求链路中的角色：拦截器与 Observable

拦截器：防护机制在请求管线中的落点

Angular 的 XSRF 防护是通过内置的 XsrfInterceptor 拦截器实现的。仓库中的 Writing Interceptors 主题文档这样定义拦截器：

拦截器是一种中间件，可以把重试、缓存、日志、认证等通用模式从单个请求中抽象出来。

结合这条链路可以理解：XsrfInterceptor 正是这类"横切关注点"的典型实现——它拦截即将发出的请求，读取 XSRF-TOKEN Cookie，若目标请求头尚未携带 Token 则自动写入 X-XSRF-TOKEN，再继续放行请求。你可以在同一个拦截器链中自定义日志、认证拦截器，XSRF 拦截器与其互不冲突，职责边界清晰。

Observable 请求模型

仓库中的 Making Requests 主题文档说明：HttpClient 为每种 HTTP 动词提供了对应方法，每个方法返回 RxJS Observable，订阅后才会真正发送请求并在服务端响应时发出结果。这意味着 Token 的附加发生在订阅触发的实际请求发送阶段，由拦截器链在底层统一完成，业务代码只需关心业务逻辑：

import { HttpClient } from '@angular/common/http';
import { Injectable } from '@angular/core';

@Injectable({ providedIn: 'root' })
export class AccountService {
  constructor(private http: HttpClient) {}

  changePassword(newPassword: string) {
    // 订阅后才真正发送；拦截器链会自动附加 X-XSRF-TOKEN 请求头
    return this.http.post('/api/account/password', { newPassword });
  }
}

只要服务端正确签发了 XSRF-TOKEN Cookie，上述 POST 请求就会自动带上 X-XSRF-TOKEN 请求头，业务代码零改动。

服务端配合：客户端防护不能替代服务端校验

仓库中的 HTTP Vulnerabilities 主题文档明确给出了一个关键结论：

跨站请求伪造（CSRF/XSRF）与跨站脚本包含（XSSI）这两类漏洞必须主要在服务端缓解，Angular 只是提供了让客户端集成更简便的辅助手段。

也就是说，Angular 的内置防护是"客户端的一半"，完整防线必须包含：

1. 服务端签发 Token：在会话建立时生成随机且不可预测的 Token，写入名为 XSRF-TOKEN（或自定义名）的 Cookie。Token 应具备足够的随机性，避免可预测。
2. 服务端校验请求头：对每个写操作请求校验 X-XSRF-TOKEN 请求头与 Cookie 值是否一致，不一致则拒绝。
3. 设置安全的 Cookie 属性：为 XSRF-TOKEN Cookie 设置 SameSite=Strict（或 Lax）属性，进一步阻止跨站请求携带该 Cookie；同时按需配置 Secure（仅 HTTPS）与 HttpOnly（注意：若设置 HttpOnly，客户端 JavaScript 将无法读取该 Cookie，因此 XSRF Token Cookie 通常不能设置 HttpOnly，需要在安全性与可用性之间权衡，或改用服务端读取的方案）。
4. 配合常规会话安全：确保登录会话本身使用 HttpOnly + Secure + SameSite 的 Cookie，并支持会话过期，缩小攻击可利用的时间窗口。

在 Angular Security 主题 文档中同样强调：Angular 内置防护针对的是跨站脚本（XSS）等常见 Web 漏洞，并不覆盖应用层安全（如认证与授权）——XSRF 防护只是纵深防御的一环，不能替代完善的鉴权体系。

验证防护生效：用 HttpTestingController 断言请求头

防护配置是否正确，可以通过测试来验证。仓库中的 Testing Requests 主题文档说明：@angular/common/http/testing 库提供工具来捕获应用发出的请求、对请求做断言，并模拟响应以仿真后端行为。这正是断言 X-XSRF-TOKEN 请求头是否被正确附加的标准做法：

import { provideHttpClient, withXsrfProtection } from '@angular/common/http';
import { HttpTestingController, provideHttpClientTesting } from '@angular/common/http/testing';
import { TestBed } from '@angular/core/testing';

import { AccountService } from './account.service';

describe('AccountService XSRF', () => {
  let service: AccountService;
  let httpMock: HttpTestingController;

  beforeEach(() => {
    TestBed.configureTestingModule({
      providers: [
        provideHttpClient(withXsrfProtection()),
        provideHttpClientTesting(),
      ],
    });
    service = TestBed.inject(AccountService);
    httpMock = TestBed.inject(HttpTestingController);
    // 模拟服务端签发的 XSRF-TOKEN Cookie
    document.cookie = 'XSRF-TOKEN=test-token-value; path=/';
  });

  afterEach(() => httpMock.verify());

  it('should attach X-XSRF-TOKEN header to POST requests', () => {
    service.changePassword('new-pass').subscribe();

    const req = httpMock.expectOne('/api/account/password');
    expect(req.request.method).toBe('POST');
    expect(req.request.headers.get('X-XSRF-TOKEN')).toBe('test-token-value');

    req.flush({ ok: true });
  });
});

这段测试能直接证明：配置生效后，POST 请求确实携带了从 Cookie 读取的 Token 请求头，从而把"配置是否正确"从人工排查变为可回归的自动化断言。

在 developer-roadmap 学习路径中的定位

本主题属于 developer-roadmap 仓库的 Angular 路线图（Angular Roadmap 中对应的 roadmaps/angular/ 目录），仓库采用 roadmaps/<roadmap-slug>/content/<topic-slug>@<node-id>.md 的组织结构，每个 Markdown 文件对应路线图上的一个主题节点（见 readme.md 的 Repository Structure 说明）。围绕 XSRF 防护，推荐按以下顺序系统学习：

• XSRF Protection：本主题，XSRF 概念与防护总览；
• Cross-site Request Forgery：漏洞成因的深入剖析与 HttpClientXsrfModule API；
• HttpClient CSRF：HttpClient 内置 CSRF 保护机制的运作细节；
• HTTP Vulnerabilities：CSRF 与 XSSI 两类 HTTP 漏洞的整体视角（服务端主责）；
• Security：Angular 内置防护的完整边界说明；
• Setting Up the Client、Making Requests、Writing Interceptors、Testing Requests：防护机制所依托的 HttpClient 配置、请求模型、拦截器与测试基础设施。

最佳实践清单

1. 默认配置先跑通：使用 provideHttpClient() 即自带 XSRF 防护，不要为"省事"而手动移除或绕过。
2. 与后端对齐命名：服务端 Cookie/请求头命名与 Angular 默认值不一致时，用 withXsrfProtection({ cookieName, headerName }) 显式对齐，避免"配置了但服务端不认"的隐性故障。
3. 服务端承担主责：务必在服务端完成 Token 签发与请求头校验，Angular 客户端机制只是集成辅助，绝不能只靠前端防御。
4. 只保护写操作：确认所有状态变更接口使用 POST/PUT/DELETE/PATCH，让防护覆盖到真正有风险的方法。
5. Cookie 属性要审慎：为会话 Cookie 设置 HttpOnly、Secure、SameSite；XSRF Token Cookie 因需 JS 读取，一般不设 HttpOnly，需与服务端方案一并权衡。
6. 用测试固化防线：通过 HttpTestingController 断言 X-XSRF-TOKEN 请求头的存在，防止后续重构中防护被无意破坏。
7. 牢记防护边界：XSRF 防护不替代认证、授权与 XSS 防护，纵深防御才是安全的完整形态。