In a Django template, what does {% csrf_token %} add to a POST form, and why does the submit fail with 403 without it?

## What the tag renders Django's **CSRF protection** has two halves that must agree on every state-changing request: - a **CSRF cookie**, named `csrftoken` by default (`CSRF_COOKIE_NAME`), holding a random 32-character secret; - a **second copy of that secret** sent in the request itself. The `{% csrf_token %}` template tag produces the second copy for ordinary HTML forms. Inside a `<form method="post">` it renders exactly one element: ```html <input type="hidden" name="csrfmiddlewaretoken" value="…64 characters…"> ``` The value is the secret **masked** with a fresh random mask each time the page is rendered, so it looks different on every load while still carrying the same secret. Rendering the tag calls `django.middleware.csrf.get_token()`, and that call is what tells the middleware to send the `csrftoken` cookie on the response. A page that never renders the tag, and never calls `get_token()` any other way, may never receive the cookie at all. ## What CsrfViewMiddleware checks `django.middleware.csrf.CsrfViewMiddleware` is in the default `MIDDLEWARE` of a new project. It does its checking in `process_view()`, after URL resolution and before your view runs, in this order: 1. If the view is marked with `csrf_exempt`, stop and let it through. 2. If the method is GET, HEAD, OPTIONS or TRACE, let it through. Every other method, including POST, PUT, PATCH and DELETE, is treated as unsafe. 3. If the request carries an `Origin` header, it must match the site's own origin or `CSRF_TRUSTED_ORIGINS`; over HTTPS with no `Origin`, the `Referer` is checked strictly instead. 4. The CSRF cookie must be present, or the request is rejected with "CSRF cookie not set." 5. The token must be present, read from the POST field `csrfmiddlewaretoken` or, failing that, from the `X-CSRFToken` header. 6. The token is unmasked and its secret compared with the cookie's secret. Any failure hands the request to the view named by `CSRF_FAILURE_VIEW` (default `django.views.csrf.csrf_failure`), which returns **403 Forbidden** and logs a warning to the `django.security.csrf` logger. ## Reading the 403 With `DEBUG = True`, the failure page shows a *reason* string. The common ones for a template form: | Reason on the 403 page | Usual cause | |---|---| | `CSRF token missing.` | the form has no `{% csrf_token %}` | | `CSRF cookie not set.` | the page that rendered the form never set the cookie, or the browser refused it | | `CSRF token from POST incorrect.` | the page is stale, for example opened before the user logged in | The last one surprises people: `django.contrib.auth.login()` calls `rotate_token()`, so a form rendered before login carries a token for the old secret. ## Making the tag work The tag reads `csrf_token` from the template context, which the built-in `csrf` context processor fills from the request. That only happens when the template is rendered with the request: - `render(request, template, context)` and every generic view do this for you; - a bare `Template(...).render(Context(...))` does not, and the tag renders nothing; - with the Jinja2 backend, use `{{ csrf_input }}` instead; it renders the same hidden input. ## Where not to use it - **GET forms** (search boxes, filters) need no token, because the middleware never checks safe methods. Adding one only copies the token into URLs, browser history and logs. - **Forms posting to another site** must not carry it: the token would be handed to that third party. Django's how-to guide warns against exactly this. ## Common mistakes - Believing CSRF only matters for logged-in users. The check applies to anonymous POSTs too, which is how Django also blocks **login CSRF**. - Fixing the 403 by removing the middleware or adding `csrf_exempt` rather than adding the tag. - Expecting the token to be tied to the session. By default it lives in its own long-lived cookie (`CSRF_COOKIE_AGE`, about a year), independent of the session. - Caching a form page with a per-view decorator such as `cache_page`. The cached HTML can be stored before the middleware has set the cookie and the `Vary: Cookie` header, so later visitors get a token with no matching cookie. Django's how-to says to put `csrf_protect` beneath `cache_page` on such views. - Shipping the default failure page to users. It is plain and developer-oriented; point `CSRF_FAILURE_VIEW` at your own view, or add a `403_csrf.html` template, which the default view renders when it exists.