在NSwag中实现Swagger UI的XSRF令牌自动注入

背景介绍

在现代Web应用开发中，跨站请求伪造(CSRF/XSRF)防护是必不可少的安全措施。当使用Swagger UI进行API测试时，如何自动注入XSRF令牌到请求头中是一个常见的需求。本文将介绍如何在NSwag项目中实现这一功能。

传统Swashbuckle解决方案

在Swashbuckle中，开发者通常使用UseRequestInterceptor功能来实现XSRF令牌的自动注入。这种方法通过在请求发送前执行JavaScript代码，从cookie中提取XSRF令牌并添加到请求头中。

(request) => { 
  var cv = document.cookie.split('; ')
    .filter(row => row.startsWith('XSRF-TOKEN='))
    .map(c => c.split('=')[1])[0]; 
  request.headers['X-XSRF-TOKEN'] = cv; 
  return request; 
}

虽然这种方法有效，但它依赖于Swashbuckle特定的功能，且代码可读性不高。

NSwag的替代方案

当迁移到NSwag时，我们可以采用更优雅的解决方案。NSwag提供了CustomHeadContent配置选项，允许我们注入自定义JavaScript代码。

实现步骤

1. 创建自定义JavaScript文件

在项目中创建一个JavaScript文件(如AntiForgery.js)，内容如下：

// 保存原始的fetch函数
const originalFetch = window.fetch;

// 重写fetch函数
window.fetch = function(url, options = {}) {
  // 从cookie中获取XSRF令牌
  const xsrfToken = document.cookie
    .split('; ')
    .find(row => row.startsWith('XSRF-TOKEN='))
    ?.split('=')[1];
  
  // 如果找到令牌且options中有headers，则添加XSRF头
  if (xsrfToken) {
    options.headers = options.headers || {};
    if (!options.headers['X-XSRF-TOKEN']) {
      options.headers['X-XSRF-TOKEN'] = xsrfToken;
    }
  }
  
  // 调用原始fetch函数
  return originalFetch(url, options);
};

2. 配置NSwag中间件

在Startup.cs或Program.cs中配置NSwag中间件：

app.UseSwaggerUi(c => {
    c.CustomHeadContent = @"<script src='./Scripts/AntiForgery.js' charset='UTF-8'></script>";
});

3. 确保JavaScript文件可访问

确保你的JavaScript文件可以通过./Scripts/AntiForgery.js路径访问。这通常意味着你需要：

• 将文件放在wwwroot/Scripts目录下
• 或者配置静态文件中间件来提供该文件

方案优势

1. 代码分离：将JavaScript逻辑单独放在文件中，提高了可维护性
2. 可重用性：相同的脚本可以在多个项目中使用
3. 灵活性：可以轻松修改脚本逻辑而不需要重新编译应用
4. 标准兼容：使用标准的fetch API拦截技术，不依赖特定框架

注意事项

1. 路径配置：确保JavaScript文件的路径配置正确，否则脚本将无法加载
2. 安全考虑：虽然这种方法方便，但要确保不会意外暴露敏感信息
3. 浏览器兼容性：现代浏览器都支持fetch API，但如果需要支持旧版浏览器，可能需要添加polyfill
4. 性能影响：拦截所有fetch请求会有轻微性能开销，但在开发环境中通常可以忽略

结论

通过重写fetch函数的方式实现XSRF令牌的自动注入，不仅解决了NSwag中缺少类似Swashbuckle的UseRequestInterceptor功能的问题，还提供了一种更加模块化和可维护的解决方案。这种方法可以轻松扩展到其他需要在请求前处理的场景，如添加认证令牌、统一错误处理等。