From 89d39dc1d77338b7436abec017e392fc1bdbe3d7 Mon Sep 17 00:00:00 2001
From: Carlton Gibson <carlton.gibson@noumenal.es>
Date: Tue, 22 Jan 2019 09:56:48 +0100
Subject: [PATCH] [2.2.x] Fixed #30091 -- Doc'd middleware ordering
 requirements with CSRF_USE_SESSIONS.

Backport of bae66e759faee8513da4b11d3fd16b044b415bdb from master.
---
 docs/ref/middleware.txt | 9 +++++++--
 docs/ref/settings.txt   | 6 ++++++
 2 files changed, 13 insertions(+), 2 deletions(-)

diff --git a/docs/ref/middleware.txt b/docs/ref/middleware.txt
index caa1c731f8..627de6edc9 100644
--- a/docs/ref/middleware.txt
+++ b/docs/ref/middleware.txt
@@ -426,6 +426,10 @@ Here are some hints about the ordering of various Django middleware classes:
 
 #. :class:`~django.contrib.sessions.middleware.SessionMiddleware`
 
+   Before any middleware that may raise an an exception to trigger an error
+   view (such as :exc:`~django.core.exceptions.PermissionDenied`) if you're
+   using :setting:`CSRF_USE_SESSIONS`.
+
    After ``UpdateCacheMiddleware``: Modifies ``Vary`` header.
 
 #. :class:`~django.middleware.http.ConditionalGetMiddleware`
@@ -450,13 +454,14 @@ Here are some hints about the ordering of various Django middleware classes:
    Close to the top: it redirects when :setting:`APPEND_SLASH` or
    :setting:`PREPEND_WWW` are set to ``True``.
 
+   After ``SessionMiddleware`` if you're using :setting:`CSRF_USE_SESSIONS`.
+
 #. :class:`~django.middleware.csrf.CsrfViewMiddleware`
 
    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`.
+   After ``SessionMiddleware`` if you're using :setting:`CSRF_USE_SESSIONS`.
 
 #. :class:`~django.contrib.auth.middleware.AuthenticationMiddleware`
 
diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt
index 5ebc26d868..dec8a39269 100644
--- a/docs/ref/settings.txt
+++ b/docs/ref/settings.txt
@@ -405,6 +405,12 @@ 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.
 
+Since the :ref:`default error views <error-views>` require the CSRF token,
+:class:`~django.contrib.sessions.middleware.SessionMiddleware` must appear in
+:setting:`MIDDLEWARE` before any middleware that may raise an exception to
+trigger an error view (such as :exc:`~django.core.exceptions.PermissionDenied`)
+if you're using ``CSRF_USE_SESSIONS``. See :ref:`middleware-ordering`.
+
 .. setting:: CSRF_FAILURE_VIEW
 
 ``CSRF_FAILURE_VIEW``