diff options
Diffstat (limited to 'docs/ref')
| -rw-r--r-- | docs/ref/csrf.txt | 29 | ||||
| -rw-r--r-- | docs/ref/middleware.txt | 3 | ||||
| -rw-r--r-- | docs/ref/settings.txt | 17 |
3 files changed, 46 insertions, 3 deletions
diff --git a/docs/ref/csrf.txt b/docs/ref/csrf.txt index 2c1b8abbf5..3d1ecc1237 100644 --- a/docs/ref/csrf.txt +++ b/docs/ref/csrf.txt @@ -64,9 +64,14 @@ XMLHttpRequest, set a custom ``X-CSRFToken`` header to the value of the CSRF token. This is often easier, because many JavaScript frameworks provide hooks that allow headers to be set on every request. -As a first step, you must get the CSRF token itself. The recommended source for -the token is the ``csrftoken`` cookie, which will be set if you've enabled CSRF -protection for your views as outlined above. +First, you must get the CSRF token. How to do that depends on whether or not +the :setting:`CSRF_USE_SESSIONS` setting is enabled. + +Acquiring the token if :setting:`CSRF_USE_SESSIONS` is ``False`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The recommended source for the token is the ``csrftoken`` cookie, which will be +set if you've enabled CSRF protection for your views as outlined above. .. note:: @@ -121,6 +126,23 @@ The above code could be simplified by using the `JavaScript Cookie library Django provides a view decorator which forces setting of the cookie: :func:`~django.views.decorators.csrf.ensure_csrf_cookie`. +Acquiring the token if :setting:`CSRF_USE_SESSIONS` is ``True`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you activate :setting:`CSRF_USE_SESSIONS`, you must include the CSRF token +in your HTML and read the token from the DOM with JavaScript: + +.. code-block:: html+django + + {% csrf_token %} + <script type="text/javascript"> + // using jQuery + var csrftoken = jQuery("[name=csrfmiddlewaretoken]").val(); + </script> + +Setting the token on the AJAX request +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Finally, you'll have to actually set the header on your AJAX request, while protecting the CSRF token from being sent to other domains using `settings.crossDomain <https://api.jquery.com/jQuery.ajax>`_ in jQuery 1.5.1 and @@ -493,6 +515,7 @@ A number of settings can be used to control Django's CSRF behavior: * :setting:`CSRF_FAILURE_VIEW` * :setting:`CSRF_HEADER_NAME` * :setting:`CSRF_TRUSTED_ORIGINS` +* :setting:`CSRF_USE_SESSIONS` Frequently Asked Questions ========================== diff --git a/docs/ref/middleware.txt b/docs/ref/middleware.txt index 94778d8a3e..dd0bae3bb3 100644 --- a/docs/ref/middleware.txt +++ b/docs/ref/middleware.txt @@ -512,6 +512,9 @@ Here are some hints about the ordering of various Django middleware classes: Before any view middleware that assumes that CSRF attacks have been dealt with. + It must come after ``SessionMiddleware`` if you're using + :setting:`CSRF_USE_SESSIONS`. + #. :class:`~django.contrib.auth.middleware.AuthenticationMiddleware` After ``SessionMiddleware``: uses session storage. diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt index 5f669115ab..87dbc89584 100644 --- a/docs/ref/settings.txt +++ b/docs/ref/settings.txt @@ -377,6 +377,22 @@ Whether to use a secure cookie for the CSRF cookie. If this is set to ``True``, the cookie will be marked as "secure," which means browsers may ensure that the cookie is only sent with an HTTPS connection. +.. setting:: CSRF_USE_SESSIONS + +``CSRF_USE_SESSIONS`` +--------------------- + +.. versionadded:: 1.11 + +Default: ``False`` + +Whether to store the CSRF token in the user's session instead of in a cookie. +It requires the use of :mod:`django.contrib.sessions`. + +Storing the CSRF token in a cookie (Django's default) is safe, but storing it +in the session is common practice in other web frameworks and therefore +sometimes demanded by security auditors. + .. setting:: CSRF_FAILURE_VIEW ``CSRF_FAILURE_VIEW`` @@ -3407,6 +3423,7 @@ Security * :setting:`CSRF_FAILURE_VIEW` * :setting:`CSRF_HEADER_NAME` * :setting:`CSRF_TRUSTED_ORIGINS` + * :setting:`CSRF_USE_SESSIONS` * :setting:`SECRET_KEY` * :setting:`X_FRAME_OPTIONS` |