Angular HttpClient CSRF 防护实战：理解 XSRF 令牌机制与配置（developer-roadmap Angular 路线图）

CSRF（Cross-Site Request Forgery，跨站请求伪造，Angular 中亦称为 XSRF）是最常见的 Web 安全漏洞之一：攻击者借助浏览器自动携带 Cookie 的特性，诱使已登录用户在不知情的情况下向受信任站点发起非预期请求。Angular 的 HttpClient 内置了一套开箱即用的 XSRF 防护机制——当功能启用后，框架会自动从 Cookie 中读取安全令牌并将其设置为后续请求的 HTTP 请求头，由服务端校验令牌以确认请求确实来自预期应用而非恶意站点。读完本文，你将掌握 CSRF 的攻击原理、HttpClient 内置防护的默认参数与启用方式、如何与服务端（双重提交 Cookie 模式）协同，以及相关的测试与拦截器扩展方法。

一、为什么要防 CSRF：攻击原理回顾

在深入 HttpClient 的防护机制之前，先明确攻击的本质。跨站请求伪造的核心在于：浏览器在向某个域名发起请求时，会自动携带该域名下的 Cookie（包括会话 Cookie），而 Cookie 的携带行为与应用本身是否同意无关。

典型的攻击链条是：

1. 用户登录了目标应用 A，浏览器中保存了 A 域名的会话 Cookie；
2. 用户在另一个标签页访问了恶意站点 B；
3. B 页面中隐藏的脚本（例如一张 <img>、一个自动提交的 <form> 或一段 fetch 代码）向 A 发起请求（如转账、改密码、删除数据）；
4. 浏览器自动带上 A 的会话 Cookie，服务端将请求误认为"已登录用户的合法操作"并执行。

与钓鱼攻击窃取凭证不同，XSRF 直接利用用户当前有效的会话，因此在认证态下尤其危险。Angular 官方学习路线图中对这一点有明确论述，可参见 xsrf-protection 与 cross-site-request-forgery 两个专题：前者强调"XSRF 利用的是用户的活跃会话而非窃取凭证"，后者则详细描述了"攻击者利用浏览器对特定域自动携带会话 Cookie 的机制执行未授权命令"这一漏洞本质。

需要说明的是：XSRF 的根因缓解主要发生在服务端。Angular 文档在 http-vulnerabilities 中明确指出，CSRF/XSRF 与 XSSI（跨站脚本包含）都必须主要在服务端进行缓解，Angular 只是提供了让客户端集成更简单的辅助机制。

二、HttpClient 内置 XSRF 保护：工作机制

HttpClient 是 Angular 提供的客户端 HTTP API，位于 @angular/common/http 包中（参见 http-client）。它的内置 XSRF 防护是一套自动化的双重提交 Cookie 模式实现，核心流程如下：

1. 服务端下发令牌：服务端在首次响应中通过 Cookie 下发一个 XSRF 令牌（默认 Cookie 名为 XSRF-TOKEN）；
2. 客户端自动回传：HttpClient 发出请求前，自动从该 Cookie 中读取令牌，并将其写入请求头（默认请求头名为 X-XSRF-TOKEN）；
3. 服务端校验：服务端对比 Cookie 中的令牌与请求头中的令牌是否一致。由于恶意站点既无法读取目标域下的 Cookie（受同源策略限制），也无法伪造请求头，因此校验通过即证明请求来自预期的前端应用。

这条链路对应原文档的核心描述："启用该功能后，框架自动从 Cookie 中读取令牌，并将其设置为后续请求的 HTTP 请求头，服务端据此校验请求是否源自预期应用。"

默认参数速查

参数	默认值	作用
Cookie 名称	XSRF-TOKEN	服务端下发、客户端读取的令牌存放位置
请求头名称	X-XSRF-TOKEN	客户端回传令牌使用的 HTTP 请求头
适用请求	非 GET/HEAD 请求	读取型请求不产生副作用，默认不附加令牌

两个默认名是框架与常见服务端框架（如 Spring Security、ASP.NET Core）之间的约定俗成，改动时需要服务端同步调整。

三、启用与配置：从模块配置到现代 provideHttpClient 写法

HttpClient 的 XSRF 防护默认处于启用状态，但你可以显式配置，以适应不同的服务端约定。

1. 传统 NgModule 方式：HttpClientXsrfModule

在基于模块的应用中，通过 HttpClientXsrfModule 配置 Cookie 名与请求头名：

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

@NgModule({
  imports: [
    HttpClientModule,
    HttpClientXsrfModule.withOptions({
      cookieName: 'XSRF-TOKEN',   // 自定义服务端下发的 Cookie 名
      headerName: 'X-XSRF-TOKEN', // 自定义回传的请求头名
    }),
  ],
})
export class AppModule {}

如果你希望彻底关闭内置的 XSRF 保护（例如服务端已通过其他方案防护），则导入 HttpClientXsrfModule.disable()。

2. 现代 Standalone 方式：provideHttpClient

在基于 provideHttpClient 的现代 Angular 应用中，等价配置如下：

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

export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(
      withXsrfConfiguration({
        cookieName: 'XSRF-TOKEN',
        headerName: 'X-XSRF-TOKEN',
      })
    ),
  ],
};

若需关闭该保护，可传入 withNoXsrfProtection()。具体 API 形态请以你所使用 Angular 版本的官方文档为准（原文档指向的官方安全指南可参见本仓库 security 专题，其中说明 Angular 内置防护主要针对 XSS 等常见漏洞，应用级安全如认证授权不在其覆盖范围）。

3. 关键前提：Cookie 与请求需同域（withCredentials）

必须强调一个容易踩坑的前提：内置 XSRF 保护依赖读取 Cookie，而浏览器只有在请求与 Cookie 同源时才允许客户端读取 Cookie 内容。因此：

• 前端与后端部署在同一域名下时，该机制天然可用；
• 若采用跨域部署（如前后端分离、不同子域），则需要后端正确设置 Access-Control-Allow-Credentials 与 Cookie 的 SameSite=None; Secure 属性，同时前端请求需要携带凭证。HttpClient 发起请求时可通过 withCredentials 选项让浏览器携带 Cookie：

this.http.post('/api/order', payload, { withCredentials: true });

四、服务端如何配合：双重提交 Cookie 校验

Angular 内置方案本质上是"双重提交 Cookie（Double Submit Cookie）"模式的客户端实现，因此服务端必须承担最终的校验职责，通常分三步：

1. 生成并下发令牌：用户会话建立时（或首次响应中），生成随机令牌，通过 Set-Cookie: XSRF-TOKEN=<token> 下发；
2. 校验请求头：对于非 GET/HEAD 的写操作请求，读取 X-XSRF-TOKEN 请求头，与 Cookie 中的令牌比对；
3. 不一致则拒绝：任一令牌缺失或不匹配，返回 403 拒绝执行。

服务端可以自行实现，也可以借助框架内置能力（例如 Spring Security 的 CSRF 过滤器、ASP.NET Core 的反伪造令牌机制）。由于 CSRF 的最终防线在服务端，客户端配置再完善，服务端不校验也是无效的。

五、底层实现视角：拦截器与 Observable

从实现角度看，HttpClient 的 XSRF 防护是作为**拦截器（Interceptor）**机制的一部分运行的。Angular 的拦截器是一类中间件，用于把重试、缓存、日志、认证等公共模式从单个请求中抽象出来（参见 writing-interceptors）。XSRF 令牌的读取与请求头注入正是发生在请求发出前的拦截阶段，与你手写的自定义拦截器处于同一请求管道中。

同时，HttpClient 的每个方法（get、post、put、delete 等）都返回 RxJS Observable，订阅后才会真正发送请求并在服务端响应时发出结果（参见 making-requests）。这意味着 XSRF 令牌的注入发生在订阅触发请求发送之时，属于请求管道的统一处理，而非每次调用时手工拼接。

六、测试与验证：如何确认防护生效

在单元测试中，可以通过 @angular/common/http/testing 提供的 HttpTestingController 捕获请求并断言请求头，从而验证 XSRF 令牌是否正确注入（参见 testing-requests 中关于 mock HTTP 后端的介绍）：

import { TestBed } from '@angular/core/testing';
import { HttpClientTestingModule, HttpTestingController } from '@angular/common/http/testing';
import { HttpClient } from '@angular/common/http';

describe('XSRF token injection', () => {
  let http: HttpClient;
  let httpTesting: HttpTestingController;

  beforeEach(() => {
    TestBed.configureTestingModule({
      imports: [HttpClientTestingModule],
    });
    http = TestBed.inject(HttpClient);
    httpTesting = TestBed.inject(HttpTestingController);
    // 模拟服务端已下发 XSRF Cookie
    document.cookie = 'XSRF-TOKEN=test-token-123';
  });

  it('在写请求中注入 X-XSRF-TOKEN 请求头', () => {
    http.post('/api/order', {}).subscribe();

    const req = httpTesting.expectOne('/api/order');
    expect(req.request.headers.get('X-XSRF-TOKEN')).toBe('test-token-123');
    req.flush({ ok: true });
  });

  afterEach(() => httpTesting.verify());
});

端到端层面，可以配合拦截器记录实际请求头，或使用浏览器开发者工具观察 X-XSRF-TOKEN 是否随写请求发送。

七、注意事项与边界

• 读取型请求默认不防护：GET/HEAD 不附加令牌，因为它们通常无副作用；若你的 GET 接口会触发数据变更，需在服务端另行设计防护。
• Cookie 读取受同源策略限制：跨域场景必须先解决 Cookie 的读写与携带问题（withCredentials + CORS 凭证 + SameSite 配置），否则令牌无法注入。
• 防护并非万能：该机制抵御的是"浏览器自动携带 Cookie"型的经典 CSRF；对于服务端不校验令牌、或攻击者能写入 Cookie 的场景（如子域 Cookie 投毒），需要额外的防护手段。
• 令牌生命周期：令牌通常绑定会话或定期轮换，服务端应保证令牌的随机性与不可预测性，并在校验失败时记录日志。

八、在 Angular 学习路线图中的位置

在本仓库的 Angular 学习路线图中，本专题与以下文档互为补充，建议按序阅读：

• http-vulnerabilities：CSRF/XSRF 与 XSSI 两类 HTTP 漏洞的整体视角；
• xsrf-protection：XSRF 概念与攻击原理专题；
• cross-site-request-forgery：包含 HttpClientXsrfModule 官方 API 入口的漏洞详解；
• http-client 与 making-requests：HttpClient 的基础使用；
• writing-interceptors 与 testing-requests：理解底层管道与验证手段。

掌握上述内容后，你便能在 Angular 应用中正确启用、配置并验证 HttpClient 的 CSRF 防护，与服务端协作构建具备基本抗 CSRF 能力的完整请求链路。