From 4c2a6fe75bad592972eafc79debc35bf944f38f7 Mon Sep 17 00:00:00 2001 From: Tim Graham Date: Wed, 3 Aug 2016 15:16:43 -0400 Subject: [PATCH] Clarified session verification with respect to the current session. --- docs/topics/auth/default.txt | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/docs/topics/auth/default.txt b/docs/topics/auth/default.txt index 7f92c12966..6735c261df 100644 --- a/docs/topics/auth/default.txt +++ b/docs/topics/auth/default.txt @@ -810,6 +810,8 @@ user to the login page or issue an HTTP 403 Forbidden response. redirects the user to the ``login_url``, optionally including the ``redirect_field_name`` if it is set. +.. currentmodule:: django.contrib.auth + .. _session-invalidation-on-password-change: Session invalidation on password change @@ -829,16 +831,20 @@ If your :setting:`AUTH_USER_MODEL` inherits from :meth:`~django.contrib.auth.models.AbstractBaseUser.get_session_auth_hash()` method, authenticated sessions will include the hash returned by this function. In the :class:`~django.contrib.auth.models.AbstractBaseUser` case, this is an -HMAC of the password field. Django verifies that the hash sent along with each -request matches the one that's computed server-side. This allows a user to log -out all of their sessions by changing their password. +HMAC of the password field. Django verifies that the hash in the session for +each request matches the one that's computed during the request. This allows a +user to log out all of their sessions by changing their password. The default password change views included with Django, -:class:`django.contrib.auth.views.PasswordChangeView` and the +:class:`~django.contrib.auth.views.PasswordChangeView` and the ``user_change_password`` view in the :mod:`django.contrib.auth` admin, update the session with the new password hash so that a user changing their own password won't log themselves out. If you have a custom password change view -and wish to have similar behavior, use this function: +and wish to have similar behavior, use the :func:`update_session_auth_hash` +function. In this case, however, if a user also wants to invalidate the session +from which they're changing their password (for example, if they believe the +session cookie on their machine was stolen), then they also need to log out +that session. .. function:: update_session_auth_hash(request, user)