Refs #16859 -- Allowed storing CSRF tokens in sessions.

Major thanks to Shai for helping to refactor the tests, and to
Shai, Tim, Florian, and others for extensive and helpful review.

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`