[1.9.x] Fixed #26201 -- Documented the consequences of rotating the CSRF token on login.

Backport of 369fa471f46cd517edf5fc82e4ef6138de3cff6 from master

1 files changed, 11 insertions, 0 deletions

diff --git a/docs/ref/csrf.txt b/docs/ref/csrf.txt
index ca94b21552..e5d32b27b3 100644
--- a/docs/ref/csrf.txt
+++ b/docs/ref/csrf.txt
@@ -227,6 +227,9 @@ The CSRF protection is based on the following things:
    every response that has called ``django.middleware.csrf.get_token()``
    (the function used internally to retrieve the CSRF token).
 
+   For security reasons, the value of the CSRF cookie is changed each time a
+   user logs in.
+
 2. A hidden form field with the name 'csrfmiddlewaretoken' present in all
    outgoing POST forms.  The value of this field is the value of the CSRF
    cookie.
@@ -505,3 +508,11 @@ because it invalidates all previous forms. Most users would be very unhappy to
 find that opening a new tab on your site has invalidated the form they had
 just spent time filling out in another tab or that a form they accessed via
 the back button could not be filled out.
+
+Why might a user encounter a CSRF validation failure after logging in?
+----------------------------------------------------------------------
+
+For security reasons, CSRF tokens are rotated each time a user logs in. Any
+page with a form generated before a login will have an old, invalid CSRF token
+and need to be reloaded. This might happen if a user uses the back button after
+a login or if they log in in a different browser tab.