说起Flask项目的CSRF防护我印象最深的是早年前接手的一个内部系统。当时系统里所有POST表单都能正常提交直到有一次安全扫描报告出来上面清清楚楚列着“跨站请求伪造风险”我才意识到自己一直忽视了这一层。后来花了一个下午把Flask-WTF的CSRFProtect接进去期间遇到了不少文档里没写透的坑包括AJAX请求怎么带token、哪些接口要豁免校验、为什么用户反馈“明明登录了却提交失败”。这篇文章就把这套完整方案整理出来从攻击原理到生产环境配置再到问题排查一次讲清楚。如果你正在维护Flask应用哪怕只是几个页面的小工具只要你接受了用户的Cookie会话就存在CSRF风险。文章内容适合已经能独立写Flask视图函数的开发者也适合刚入门、想搞清楚“模板里那个csrf_token到底有什么用”的新手。我会先从攻击场景说起再给出可直接抄走的代码配置最后把排错经验一并奉上。1. 先搞懂CSRF攻击的实际场景1.1 一次看似无害的图片请求CSRF的全称是Cross-Site Request Forgery中文叫跨站请求伪造。理解它最直接的方式是看一个经典案例。假设你登录了某个博客后台浏览器里存着这个后台的会话Cookie。此时你又打开了另一个陌生网页这个网页里埋了一张“图片”img srchttps://blog.example.com/admin/post/delete/123 /浏览器解析到img标签时会向这个地址发一个GET请求。关键问题来了浏览器会把这个博客域下的Cookie一起带上因为请求目标就是这个域名。如果博客后台的删除操作是用GET实现的或者某个POST接口恰好能被表单触发攻击者只需要把图片换成一段自动提交的隐藏表单就能在用户不知情的情况下完成操作。这里不少人会混淆CORS和CSRF的区别。CORS管的是“能不能读取响应”CSRF利用的则是“请求本身被服务器执行了”。就算浏览器因为同源策略无法读取返回结果请求已经在服务器端产生副作用了。所以攻击面是真实存在的尤其在那些“信任Cookie、不校验来源”的老系统里。我习惯用一个生活类比来解释你的家门钥匙就挂在门外的挂钩上任何人都能拿它开门门锁本身分不清来的人是你还是别人。CSRF防护要做的就是给钥匙加一道额外的“暗号”让门锁确认“这个人是自己人”。1.2 Flask项目的暴露面分析不同Flask项目暴露的CSRF风险点不太一样我建议你在动手配置之前先把自己的项目“盘”一遍。大方向上分三类传统表单提交登录、发布文章、删除评论这类最典型直接用form提交Cookie自动携带攻击者构造一个同款表单就能触发。AJAX异步请求很多项目用fetch或axios接口接收JSON数据虽然Content-Type不是表单格式但攻击者仍然可以跨站发POSTHeader里的Content-Type完全可以伪造。前后端分离的API如果你的Flask只当后端API使用前端跑在另一个域名下方案就不能照搬传统模板项目你得考虑token放在哪里、如何通过Header传过来。第三方回调接口支付回调、短信状态推送这类外部系统调用的接口不能用常规CSRF逻辑去卡因为对方没有你的页面自然拿不到token。你不需要在一开始就把所有场景想清楚但心里要有数哪些接口是“用户主动操作触发”的哪些是“机器自动调用”的。前者是CSRF防护的重点后者需要单独的验签方案。知道这个区分之后下面接Flask-WTF时就不会乱套。2. 防护方案选型与Flask-WTF接入准备2.1 方案对比为什么首选Flask-WTFFlask框架本身没有内置CSRF防护这点和Django不同。Flask给开发者足够的自由但也意味着“默认裸奔”。市面上常见的CSRF防护方案有这么几种方案核心思路优点缺点Session Token服务端生成token存session页面请求时带上提交时比对实现简单、兼容性好、使用广泛依赖session存储双重提交Cookie随机token同时放在Cookie和请求参数中服务端比对两者无需服务端存储、适合API场景子域污染时可能失效需要额外处理SameSite Cookie浏览器层面限制跨站请求携带Cookie零代码、性能好依赖浏览器支持部分嵌套场景会误伤自定义Header校验要求每个请求必须带自定义Header能阻止绝大多数跨站请求需要前端配合无法阻止同站恶意请求单独说哪种方案最完美都不现实生产环境里通常组合使用。Flask-WTF内置的CSRFProtect采用第一种Session Token方案扩展成熟、API稳定社区使用量大出问题能搜到大量现成案例。它默认拦截所有非安全方法的请求开发者只需要在模板或AJAX里把token带上接入成本最低。2.2 环境准备与基础配置接入Flask-WTF的第一步自然是安装依赖pip install flask-wtfFlask-WTF会依赖WTForms如果项目中还没有会一并装好。这不会影响你现有的表单逻辑即使你没在用WTForms写表单仍可以单独利用它的CSRFProtect做全局防护。然后是初始化配置。在我的一个模拟项目X里配置长这样from flask import Flask from flask_wtf import CSRFProtect app Flask(__name__) app.config[SECRET_KEY] your-secret-key-here app.config[WTF_CSRF_ENABLED] True # token有效时间单位秒默认3600 app.config[WTF_CSRF_TIME_LIMIT] 3600 csrf CSRFProtect() csrf.init_app(app)这里有三处容易踩坑。第一SECRET_KEY必须设置CSRF token的生成依赖它不设置的话Flask-WTF会直接报错。第二WTF_CSRF_ENABLED默认就是True写不写都能生效但写出来便于维护者理解。第三WTF_CSRF_TIME_LIMIT控制token的有效期如果你发现用户长时间停留在表单页、提交时提示token过期可以考虑调大这个值但调大也会增加安全窗口要权衡。如果你用的是应用工厂模式初始化方式略有区别csrf CSRFProtect() def create_app(): app Flask(__name__) app.config.from_object(config.ProdConfig) csrf.init_app(app) return app这种延迟绑定方式在大型项目里更常见好处是csrf实例可以在蓝图模块里直接导入使用。实测下来很稳没有遇到什么坑。3. 核心配置与实操演示3.1 表单场景全局防护与模板tokenCSRFProtect初始化之后你再看自己的表单页面所有POST请求都会被拦截返回400错误。这是正常现象因为你还没把token渲染到模板里。在Jinja2模板中给表单加一个隐藏字段form methodpost action{{ url_for(post.delete, post_idpost.id) }} input typehidden namecsrf_token value{{ csrf_token() }} button typesubmit删除文章/button /formcsrf_token()是Flask-WTF注入到模板全局的函数每次渲染都会返回当前会话对应的token值。这里有个容易被忽略的细节隐藏字段必须放在form标签内部放在外面就起不到作用了因为提交表单时浏览器只会把form内部的字段一并发送。我自己就见过有人把token输出在页面底部然后排查了半天。如果你用Flask-WTF的FlaskForm来定义表单模板可以更简洁form methodpost {{ form.hidden_tag() }} !-- 其他字段 -- /formhidden_tag()会自动渲染一个包含csrf_token的隐藏输入框以及其他需要隐藏的字段。使用传统表单时无需更多改动提交时token会跟随表单数据一起POST到服务器Flask-WTF自动完成校验。但请注意只有非安全方法的请求才需要验证GET、HEAD、OPTIONS、TRACE默认不校验这个行为由WTF_CSRF_METHODS控制默认就是[POST, PUT, PATCH, DELETE]。所以你不需要担心搜索结果页因为带token而报错。3.2 AJAX请求头三种传Token的方式实测现代项目里AJAX请求比传统表单多得多。Flask-WTF提供了一套请求头校验机制只要请求头里带上了X-CSRFToken还有几个同义请求头名也支持并且值和session里的token一致就能通过校验。具体支持哪些请求头名可以看Flask-WTF源码中csrf模块的_get_csrf_token函数。前端把token传给后端我实测下来有三种常用方式按推荐程度排序。方式一页面meta标签存储JS读取后统一加到请求头。meta namecsrf-token content{{ csrf_token() }}const token document.querySelector(meta[namecsrf-token]).getAttribute(content); fetch(/api/comment, { method: POST, headers: { Content-Type: application/json, X-CSRFToken: token }, body: JSON.stringify({ content: 这是一条新评论 }) });这种方式适合页面数量不多、整页刷新的传统项目meta标签渲染成本低任何JS代码都能拿到token不用依赖第三方库。方式二全局设置axios默认请求头。axios.defaults.xsrfHeaderName X-CSRFToken; axios.defaults.xsrfCookieName csrf_token;如果模板里没有token变量可用或整体是一个单页应用可以把token写在不含HttpOnly标记的Cookie里然后由axios自动读取。具体做法是服务端设置了一个Cookie名为csrf_tokenaxios默认就会尝试读取这个Cookie自动填充。不过要特别注意这样做的前提是这个Cookie不能加HttpOnly否则JS拿不到。方式三统一的请求拦截器适合中大型项目。// 假设有一个名为apiFetch的封装函数 function apiFetch(url, options {}) { const token document.querySelector(meta[namecsrf-token]).getAttribute(content); options.headers { ...options.headers, X-CSRFToken: token }; return fetch(url, options); }把所有请求统一走apiFetch以后就算接口多了也只需要维护一个地方。关于AJAX场景我最想提醒的一点是不要忘了设置credentials或withCredentials。如果你跨域请求并且不想带Cookie那CSRF保护的意义就变了因为浏览器不会自动携带CookieCSRF风险降低但很多Flask应用是samesite类型部署不涉及不过前后端分离部署时务必确认Cookie的SameSite和Domain配置。3.3 API接口场景前后端分离的token方案前后端分离后Flask往往只提供JSON接口前端完全由静态资源服务器托管。这种情况下模板里直接渲染csrf_token()可能不再适用因为前端和后端不在同一个源。我推荐的方式是后端提供一个接口返回token前端在应用启动时获取一次然后放到内存里不要放localStorage原因后面细说。后端from flask import jsonify, session app.route(/api/csrf-token) def get_csrf_token(): # 确保session已创建 if not session.get(_fresh): session[_fresh] True return jsonify({ csrf_token: session[csrf_token] })实际上Flask-WTF生成token的函数是私有的更通用的写法是直接引用模板函数对应的底层方法flask_wtf.csrf.generate_csrf()它会基于session动态生成token。接口可以改成from flask_wtf.csrf import generate_csrf app.route(/api/csrf-token) def get_csrf_token(): return jsonify({ csrf_token: generate_csrf() })前端在封装axios时先请求这个接口拿到token后写入默认头const res await axios.get(/api/csrf-token); axios.defaults.headers.common[X-CSRFToken] res.data.csrf_token;之后所有的POST、PUT、PATCH、DELETE请求都会自动携带token。为什么我明确说不建议把token放到localStorage因为localStorage对同一源下的所有脚本都开放一旦站点存在XSS漏洞攻击者可以直接读取token等于连CSRF防护一起攻破了。放在内存变量里刷新页面后丢失恰好符合token短时有效的特点。还有一种常见做法是后端把token种到Cookie里不带HttpOnly前端读取后放入请求头这属于双重提交Cookie的变体也能用但前提是明确了解子域不能过宽。如果你不想额外增加一次请求也可以在登录接口的返回体里顺便返回csrf_token。登录接口本身必须是CSRF豁免的否则会陷入“先有鸡还是先有蛋”的死循环这个问题下面专门讲。3.4 排除特定端点的正确姿势有些接口天然不适合CSRF token校验典型场景是第三方回调。比如支付平台通知你的服务器“订单已支付”这个请求是支付平台发起的它没有你页面里的token你不可能要求它带上。如果硬用CSRF去卡回调会全部失败。Flask-WTF提供了exempt装饰器from flask_wtf import CSRFProtect csrf CSRFProtect() app.route(/payment/callback, methods[POST]) csrf.exempt def payment_callback(): # 处理支付回调逻辑 pass需要注意的是装饰器的顺序csrf.exempt要放在app.route的下面一层也就是先套用exempt再被route登记。两个装饰器的顺序不能反反了会导致exempt失效或者路由注册异常。不过我得提醒一句豁免只是“不做CSRF校验”不等于这个接口不需要安全防护。支付回调这类接口应该采用独立的签名验证机制通常是回调参数里带上签名串服务端用约定密钥验签。签名验证通过后才能继续处理业务。把这种做法结合起来安全性才算闭环。还有一种情况需要豁免登录接口本身。用户还没登录Session里可能也没有token如果用全局CSRF拦截用户连登录都提交不进去。常规做法是登录页正常渲染csrf_token()隐藏字段登录接口不豁免也能过因为你能拿到token。但部分前后端分离的项目会在登录前先拉取token那登录接口就需要豁免否则首次获取token的请求就被拦了。无论是哪种豁免我建议在代码里写清楚理由例如csrf.exempt # 支付回调基于签名验签不使用CSRF app.route(/payment/callback, methods[POST])两个月后的你自己看到这行注释会感谢今天的你。4. 常见问题与排查技巧实录4.1 问题速查表把CSRFProtect接入项目后我陆续接到过不少同事和网友的提问。这里整理成速查表按现象、原因、解决方案的路子来现象可能原因排查思路提交表单报400 “CSRF token missing”模板里没有渲染token或token不在form内部检查form代码确认csrf_token()字段存在且位于form内提示“CSRF token invalid”SECRET_KEY变化、session过期、token被篡改检查配置是否改了SECRET_KEY确认WTF_CSRF_TIME_LIMIT设置对比同一个会话内两次token值GET请求也被拦截有人手动改了WTF_CSRF_METHODS把GET加了进去查看配置确认默认安全方法没被意外修改所有请求都被拦只有部分route正常蓝图中豁免装饰器顺序错误检查装饰器嵌套顺序AJAX请求报403/400但表单正常请求头没带X-CSRFToken或带的值和session不一致浏览器开发者工具里确认请求头前端打断点看token值换了台服务器后所有提交失败多实例部署时SECRET_KEY不一致导致不同节点的token无法互验所有实例统一SECRET_KEY配置或改共享session存储4.2 典型案例复盘案例一nginx剥离了自定义请求头。有个项目前端在axios里设了X-CSRFToken本地联调一切正常一上测试环境就400。查了半天最后发现nginx配置文件里有一行proxy_set_header X-CSRFToken 是另外一个同事为了“安全”手动加的导致请求头到后端时被清空。这个问题提醒我接入CSRF后如果要排查请求头类问题先看反向代理有没有“清洗”请求头。案例二部署了多台应用服务器但SECRET_KEY不同。Flask的Session Cookie和CSRF token都依赖SECRET_KEY进行签名部署时如果每个节点用各自的SECRET_KEY用户在节点A拿到的token到节点B上验证就会失败。解决的方法是统一写成环境变量在所有实例中读取同一个值。案例三用户停留页面太久提交时token过期。默认WTF_CSRF_TIME_LIMIT是3600秒用户打开一个表单页放了一小时以上再提交就会报“CSRF token invalid”。这类问题的难点在于用户感知很奇怪——明明登录状态还在怎么提交就失败了。处理方式有两种一是调大time_limit二是前端在页面停留一段时间后自动重新获取token。我更推荐后者。4.3 用户体验优化与错误处理CSRF校验失败默认返回400页面对用户来说相当不友好。生产环境里我建议把错误处理成接口形式让前端能明确感知并引导用户刷新页面from flask_wtf.csrf import CSRFError from flask import jsonify app.errorhandler(CSRFError) def handle_csrf_error(e): return jsonify({ code: 400, message: 页面已过期请刷新后重试, detail: str(e.description) }), 400传统模板项目也可以渲染一个专门的错误页提示用户“当前页面已过期请返回重新操作”并提供一个返回按钮。这样至少比白屏400强用户不会以为自己网站坏了。顺带一提在使用Flask-DebugToolbar时有时它会自动注入一些测试POST请求这些请求可能因为没有token而被拦截让人误以为CSRF配置有误。排查时先关掉这个扩展再试能省不少时间。4.4 进阶加固同源策略与双保险单纯依靠CSRF token已经能防住绝大多数攻击但你可以再加一道浏览器层面的保险SameSiteCookie属性。Flask 2.0及以上版本配置非常简单app.config[SESSION_COOKIE_SAMESITE] LaxSameSiteLax意味着跨站请求默认不再携带Cookie但同站页面里的GET请求仍然可以携带用户日常点击链接不受影响。这个设置对传统表单和AJAX是两层防护即便攻击者想尽办法构造了跨站请求浏览器这关就会拦下Cookie携带CSRF攻击直接缺少了“身份凭证”。选择Strict会更严格但可能会影响从邮件、微信等外部来源点击链接进入站点的体验因为首次跳转不带Cookie用户会被当成未登录状态。建议先用Lax观察一段时间确认影响范围后再评估是否升级。另外如果你部署了多个子域比如app.example.com和api.example.com要特别注意Cookie的Domain属性。设置得当可以省心设置过宽比如整个example.com域则会让所有子域共享CookieCSRF攻击面反而扩大了。5. 写在实际操作之后把CSRF防护接入Flask项目本质上不是多复杂的技术活但涉及的点很碎模板要加字段、AJAX要加请求头、第三方回调要豁免、多实例部署要统一密钥、前置nginx不能乱删请求头。每一个点单独看都很简单组合在一起就容易出“本地好好的一上线就400”的诡异问题。我在实际项目里最受益的一个习惯是接入CSRFProtect后把全项目的请求梳理一遍按“浏览器页面发起”和“机器对机器调用”两个维度分类前者走CSRF校验后者走签名验签。这样既不会漏防护也不会错杀外部渠道。另一个习惯是统一封装前端请求层不管是fetch还是axios都走同一个入口不然每个页面自己写请求token偶尔带上偶尔不带排查起来非常头疼。后续如果你的项目长出了更多API接口或者开始做前后端彻底分离可以把知识库里的方案换成“双重提交CookieSameSite”组合那套体系更适合无状态服务。就目前而言Flask-WTF这套方案已经足够解决绝大多数Flask项目的CSRF防护问题。