Debian Codegraph @

docs/howto/csrf.txt

raw
1 .. _using-csrf:
2
3 ===================================
4 How to use Django's CSRF protection
5 ===================================
6
7 To take advantage of CSRF protection in your views, follow these steps:
8
9 #. The CSRF middleware is activated by default in the :setting:`MIDDLEWARE`
10 setting. If you override that setting, remember that
11 ``'django.middleware.csrf.CsrfViewMiddleware'`` should come before any view
12 middleware that assume that CSRF attacks have been dealt with.
13
14 If you disabled it, which is not recommended, you can use
15 :func:`~django.views.decorators.csrf.csrf_protect` on particular views
16 you want to protect (see below).
17
18 #. In any template that uses a POST form, use the :ttag:`csrf_token` tag inside
19 the ``<form>`` element if the form is for an internal URL, e.g.:
20
21 .. code-block:: html+django
22
23 <form method="post">{% csrf_token %}
24
25 This should not be done for POST forms that target external URLs, since
26 that would cause the CSRF token to be leaked, leading to a vulnerability.
27
28 #. In the corresponding view functions, ensure that
29 :class:`~django.template.RequestContext` is used to render the response so
30 that ``{% csrf_token %}`` will work properly. If you're using the
31 :func:`~django.shortcuts.render` function, generic views, or contrib apps,
32 you are covered already since these all use ``RequestContext``.
33
34 .. _csrf-ajax:
35
36 Using CSRF protection with AJAX
37 ===============================
38
39 While the above method can be used for AJAX POST requests, it has some
40 inconveniences: you have to remember to pass the CSRF token in as POST data with
41 every POST request. For this reason, there is an alternative method: on each
42 XMLHttpRequest, set a custom ``X-CSRFToken`` header (as specified by the
43 :setting:`CSRF_HEADER_NAME` setting) to the value of the CSRF token. This is
44 often easier because many JavaScript frameworks provide hooks that allow
45 headers to be set on every request.
46
47 First, you must get the CSRF token. How to do that depends on whether or not
48 the :setting:`CSRF_USE_SESSIONS` and :setting:`CSRF_COOKIE_HTTPONLY` settings
49 are enabled.
50
51 .. _acquiring-csrf-token-from-cookie:
52
53 Acquiring the token if :setting:`CSRF_USE_SESSIONS` and :setting:`CSRF_COOKIE_HTTPONLY` are ``False``
54 -----------------------------------------------------------------------------------------------------
55
56 The recommended source for the token is the ``csrftoken`` cookie, which will be
57 set if you've enabled CSRF protection for your views as outlined above.
58
59 The CSRF token cookie is named ``csrftoken`` by default, but you can control
60 the cookie name via the :setting:`CSRF_COOKIE_NAME` setting.
61
62 You can acquire the token like this:
63
64 .. code-block:: javascript
65
66 function getCookie(name) {
67 let cookieValue = null;
68 if (document.cookie && document.cookie !== '') {
69 const cookies = document.cookie.split(';');
70 for (let i = 0; i < cookies.length; i++) {
71 const cookie = cookies[i].trim();
72 // Does this cookie string begin with the name we want?
73 if (cookie.substring(0, name.length + 1) === (name + '=')) {
74 cookieValue = decodeURIComponent(cookie.substring(name.length + 1));
75 break;
76 }
77 }
78 }
79 return cookieValue;
80 }
81 const csrftoken = getCookie('csrftoken');
82
83 The above code could be simplified by using the `JavaScript Cookie library
84 <https://github.com/js-cookie/js-cookie/>`_ to replace ``getCookie``:
85
86 .. code-block:: javascript
87
88 const csrftoken = Cookies.get('csrftoken');
89
90 .. note::
91
92 The CSRF token is also present in the DOM in a masked form, but only if
93 explicitly included using :ttag:`csrf_token` in a template. The cookie
94 contains the canonical, unmasked token. The
95 :class:`~django.middleware.csrf.CsrfViewMiddleware` will accept either.
96 However, in order to protect against `BREACH`_ attacks, it's recommended to
97 use a masked token.
98
99 .. warning::
100
101 If your view is not rendering a template containing the :ttag:`csrf_token`
102 template tag, Django might not set the CSRF token cookie. This is common in
103 cases where forms are dynamically added to the page. To address this case,
104 Django provides a view decorator which forces setting of the cookie:
105 :func:`~django.views.decorators.csrf.ensure_csrf_cookie`.
106
107 .. _BREACH: https://www.breachattack.com/
108
109 .. _acquiring-csrf-token-from-html:
110
111 Acquiring the token if :setting:`CSRF_USE_SESSIONS` or :setting:`CSRF_COOKIE_HTTPONLY` is ``True``
112 --------------------------------------------------------------------------------------------------
113
114 If you activate :setting:`CSRF_USE_SESSIONS` or
115 :setting:`CSRF_COOKIE_HTTPONLY`, you must include the CSRF token in your HTML
116 and read the token from the DOM with JavaScript:
117
118 .. code-block:: html+django
119
120 {% csrf_token %}
121 <script>
122 const csrftoken = document.querySelector('[name=csrfmiddlewaretoken]').value;
123 </script>
124
125 Setting the token on the AJAX request
126 -------------------------------------
127
128 Finally, you'll need to set the header on your AJAX request. Using the
129 `fetch()`_ API:
130
131 .. code-block:: javascript
132
133 const request = new Request(
134 /* URL */,
135 {
136 method: 'POST',
137 headers: {'X-CSRFToken': csrftoken},
138 mode: 'same-origin' // Do not send CSRF token to another domain.
139 }
140 );
141 fetch(request).then(function(response) {
142 // ...
143 });
144
145 .. _fetch(): https://developer.mozilla.org/en-US/docs/Web/API/fetch
146
147 Using CSRF protection in Jinja2 templates
148 =========================================
149
150 Django's :class:`~django.template.backends.jinja2.Jinja2` template backend
151 adds ``{{ csrf_input }}`` to the context of all templates which is equivalent
152 to ``{% csrf_token %}`` in the Django template language. For example:
153
154 .. code-block:: html+jinja
155
156 <form method="post">{{ csrf_input }}
157
158 Using the decorator method
159 ==========================
160
161 Rather than adding ``CsrfViewMiddleware`` as a blanket protection, you can use
162 the :func:`~django.views.decorators.csrf.csrf_protect` decorator, which has
163 exactly the same functionality, on particular views that need the protection.
164 It must be used **both** on views that insert the CSRF token in the output, and
165 on those that accept the POST form data. (These are often the same view
166 function, but not always).
167
168 Use of the decorator by itself is **not recommended**, since if you forget to
169 use it, you will have a security hole. The 'belt and braces' strategy of using
170 both is fine, and will incur minimal overhead.
171
172 .. _csrf-rejected-requests:
173
174 Handling rejected requests
175 ==========================
176
177 By default, a '403 Forbidden' response is sent to the user if an incoming
178 request fails the checks performed by ``CsrfViewMiddleware``. This should
179 usually only be seen when there is a genuine Cross Site Request Forgery, or
180 when, due to a programming error, the CSRF token has not been included with a
181 POST form.
182
183 The error page, however, is not very friendly, so you may want to provide your
184 own view for handling this condition. To do this, set the
185 :setting:`CSRF_FAILURE_VIEW` setting.
186
187 CSRF failures are logged as warnings to the :ref:`django.security.csrf
188 <django-security-logger>` logger.
189
190 Using CSRF protection with caching
191 ==================================
192
193 If the :ttag:`csrf_token` template tag is used by a template (or the
194 ``get_token`` function is called some other way), ``CsrfViewMiddleware`` will
195 add a cookie and a ``Vary: Cookie`` header to the response. This means that the
196 middleware will play well with the cache middleware if it is used as instructed
197 (``UpdateCacheMiddleware`` goes before all other middleware).
198
199 However, if you use cache decorators on individual views, the CSRF middleware
200 will not yet have been able to set the Vary header or the CSRF cookie, and the
201 response will be cached without either one. In this case, on any views that
202 will require a CSRF token to be inserted you should use the
203 :func:`django.views.decorators.csrf.csrf_protect` decorator first::
204
205 from django.views.decorators.cache import cache_page
206 from django.views.decorators.csrf import csrf_protect
207
208
209 @cache_page(60 * 15)
210 @csrf_protect
211 def my_view(request): ...
212
213 If you are using class-based views, you can refer to :ref:`Decorating
214 class-based views<decorating-class-based-views>`.
215
216 Testing and CSRF protection
217 ===========================
218
219 The ``CsrfViewMiddleware`` will usually be a big hindrance to testing view
220 functions, due to the need for the CSRF token which must be sent with every POST
221 request. For this reason, Django's HTTP client for tests has been modified to
222 set a flag on requests which relaxes the middleware and the ``csrf_protect``
223 decorator so that they no longer rejects requests. In every other respect
224 (e.g. sending cookies etc.), they behave the same.
225
226 If, for some reason, you *want* the test client to perform CSRF
227 checks, you can create an instance of the test client that enforces
228 CSRF checks:
229
230 .. code-block:: pycon
231
232 >>> from django.test import Client
233 >>> csrf_client = Client(enforce_csrf_checks=True)
234
235 Edge cases
236 ==========
237
238 Certain views can have unusual requirements that mean they don't fit the normal
239 pattern envisaged here. A number of utilities can be useful in these
240 situations. The scenarios they might be needed in are described in the following
241 section.
242
243 Disabling CSRF protection for just a few views
244 ----------------------------------------------
245
246 Most views requires CSRF protection, but a few do not.
247
248 Solution: rather than disabling the middleware and applying ``csrf_protect`` to
249 all the views that need it, enable the middleware and use
250 :func:`~django.views.decorators.csrf.csrf_exempt`.
251
252 Setting the token when ``CsrfViewMiddleware.process_view()`` is not used
253 ------------------------------------------------------------------------
254
255 There are cases when ``CsrfViewMiddleware.process_view`` may not have run
256 before your view is run - 404 and 500 handlers, for example - but you still
257 need the CSRF token in a form.
258
259 Solution: use :func:`~django.views.decorators.csrf.requires_csrf_token`
260
261 Including the CSRF token in an unprotected view
262 -----------------------------------------------
263
264 There may be some views that are unprotected and have been exempted by
265 ``csrf_exempt``, but still need to include the CSRF token.
266
267 Solution: use :func:`~django.views.decorators.csrf.csrf_exempt` followed by
268 :func:`~django.views.decorators.csrf.requires_csrf_token`. (i.e. ``requires_csrf_token``
269 should be the innermost decorator).
270
271 Protecting a view for only one path
272 -----------------------------------
273
274 A view needs CSRF protection under one set of conditions only, and mustn't have
275 it for the rest of the time.
276
277 Solution: use :func:`~django.views.decorators.csrf.csrf_exempt` for the whole
278 view function, and :func:`~django.views.decorators.csrf.csrf_protect` for the
279 path within it that needs protection. Example::
280
281 from django.views.decorators.csrf import csrf_exempt, csrf_protect
282
283
284 @csrf_exempt
285 def my_view(request):
286 @csrf_protect
287 def protected_path(request):
288 do_something()
289
290 if some_condition():
291 return protected_path(request)
292 else:
293 do_something_else()
294
295 Protecting a page that uses AJAX without an HTML form
296 -----------------------------------------------------
297
298 A page makes a POST request via AJAX, and the page does not have an HTML form
299 with a :ttag:`csrf_token` that would cause the required CSRF cookie to be sent.
300
301 Solution: use :func:`~django.views.decorators.csrf.ensure_csrf_cookie` on the
302 view that sends the page.
303
304 CSRF protection in reusable applications
305 ========================================
306
307 Because it is possible for the developer to turn off the ``CsrfViewMiddleware``,
308 all relevant views in contrib apps use the ``csrf_protect`` decorator to ensure
309 the security of these applications against CSRF. It is recommended that the
310 developers of other reusable apps that want the same guarantees also use the
311 ``csrf_protect`` decorator on their views.