工作原理¶

CSRF 保护基于以下内容

1. 一个 CSRF cookie，它是一个随机的秘密值，其他网站无法访问。

   CsrfViewMiddleware 在每次调用 django.middleware.csrf.get_token() 时都会随响应发送此 cookie。它还可以在其他情况下发送它。出于安全原因，每次用户登录时，密钥的值都会更改。

2. 所有传出 POST 表单中都存在一个名为“csrfmiddlewaretoken”的隐藏表单字段。

   为了防止 BREACH 攻击，此字段的值不仅仅是密钥。它使用掩码在每次响应中以不同的方式进行混淆。每次调用 get_token() 时都会随机生成掩码，因此每次表单字段值都不同。

   此部分由模板标记完成。

3. 对于所有不使用 HTTP GET、HEAD、OPTIONS 或 TRACE 的传入请求，必须存在 CSRF cookie，并且“csrfmiddlewaretoken”字段必须存在且正确。如果不是，用户将收到 403 错误。

   在验证“csrfmiddlewaretoken”字段值时，仅将密钥（而不是完整令牌）与 cookie 值中的密钥进行比较。这允许使用不断变化的令牌。虽然每个请求都可以使用自己的令牌，但密钥对于所有请求都是通用的。

   此检查由 CsrfViewMiddleware 完成。

4. CsrfViewMiddleware 验证 Origin 头（如果由浏览器提供），并将其与当前主机和 CSRF_TRUSTED_ORIGINS 设置进行比较。这提供了针对跨子域攻击的保护。

5. 此外，对于 HTTPS 请求，如果未提供 Origin 头，CsrfViewMiddleware 将执行严格的引用检查。这意味着即使子域可以在您的域上设置或修改 cookie，它也无法强制用户向您的应用程序提交，因为该请求不会来自您自己的确切域。

   这还解决了在使用会话独立机密时在 HTTPS 下可能发生的中间人攻击，因为 HTTP Set-Cookie 头（不幸的是）被客户端接受，即使它们正在与 HTTPS 下的网站通信。（HTTP 请求不执行引用检查，因为 Referer 头的存在在 HTTP 下不够可靠。）

   如果设置了 CSRF_COOKIE_DOMAIN 设置，则将引用与之进行比较。您可以通过包含一个前导点来允许跨子域请求。例如，CSRF_COOKIE_DOMAIN = '.example.com' 将允许来自 www.example.com 和 api.example.com 的 POST 请求。如果未设置该设置，则引用必须与 HTTP Host 头匹配。

   可以使用 CSRF_TRUSTED_ORIGINS 设置将接受的引用扩展到当前主机或 cookie 域之外。

这确保了只有来自受信任域的表单才能用于将数据 POST 回来。

它故意忽略 GET 请求（以及 RFC 9110#section-9.2.1 定义为“安全”的其他请求）。这些请求永远不应有任何潜在的危险副作用，因此使用 GET 请求进行的 CSRF 攻击应该是无害的。 RFC 9110#section-9.2.1 将 POST、PUT 和 DELETE 定义为“不安全”，并且为了最大程度的保护，所有其他方法也都被假定为不安全。

CSRF 保护无法抵御中间人攻击，因此请将 HTTPS 与 HTTP 严格传输安全 结合使用。它还假定 验证 HOST 头 并且您的网站上没有任何 跨站点脚本漏洞（因为 XSS 漏洞已经允许攻击者执行 CSRF 漏洞允许的任何操作，并且更糟）。

限制¶

网站中的子域将能够为整个域在客户端上设置 cookie。通过设置 cookie 并使用相应的令牌，子域将能够规避 CSRF 保护。避免这种情况的唯一方法是确保子域由受信任的用户控制（或至少无法设置 cookie）。请注意，即使没有 CSRF，还有其他漏洞，例如会话固定，这使得将子域提供给不受信任的方成为一个糟糕的主意，并且这些漏洞无法通过当前浏览器轻松修复。

实用工具¶

以下示例假定您正在使用基于函数的视图。如果您正在使用基于类的视图，则可以参考 装饰基于类的视图。

csrf_exempt(view)¶

此装饰器将视图标记为免受中间件确保的保护。示例

from django.http import HttpResponse
from django.views.decorators.csrf import csrf_exempt


@csrf_exempt
def my_view(request):
    return HttpResponse("Hello world")

Django 5.0 中已更改

添加了对包装异步视图函数的支持。

csrf_protect(view)¶

装饰器，为视图提供 CsrfViewMiddleware 的保护。

用法

from django.shortcuts import render
from django.views.decorators.csrf import csrf_protect


@csrf_protect
def my_view(request):
    c = {}
    # ...
    return render(request, "a_template.html", c)

Django 5.0 中已更改

添加了对包装异步视图函数的支持。

requires_csrf_token(view)¶

通常，如果 CsrfViewMiddleware.process_view 或类似的 csrf_protect 尚未运行，csrf_token 模板标记将不起作用。视图装饰器 requires_csrf_token 可用于确保模板标记确实有效。此装饰器的工作方式类似于 csrf_protect，但绝不会拒绝传入的请求。

示例

from django.shortcuts import render
from django.views.decorators.csrf import requires_csrf_token


@requires_csrf_token
def my_view(request):
    c = {}
    # ...
    return render(request, "a_template.html", c)

Django 5.0 中已更改

添加了对包装异步视图函数的支持。

ensure_csrf_cookie(view)¶

此装饰器强制视图发送 CSRF cookie。

Django 5.0 中已更改

添加了对包装异步视图函数的支持。

设置¶

可以使用许多设置来控制 Django 的 CSRF 行为

• CSRF_COOKIE_AGE
• CSRF_COOKIE_DOMAIN
• CSRF_COOKIE_HTTPONLY
• CSRF_COOKIE_NAME
• CSRF_COOKIE_PATH
• CSRF_COOKIE_SAMESITE
• CSRF_COOKIE_SECURE
• CSRF_FAILURE_VIEW
• CSRF_HEADER_NAME
• CSRF_TRUSTED_ORIGINS
• CSRF_USE_SESSIONS

常见问题¶