Fixed #25029 -- Added PersistentRemoteUserMiddleware for login-page-only external authentication.

1 files changed, 24 insertions, 1 deletions

diff --git a/docs/howto/auth-remote-user.txt b/docs/howto/auth-remote-user.txt
index 39454c5f63..bef562d565 100644
--- a/docs/howto/auth-remote-user.txt
+++ b/docs/howto/auth-remote-user.txt
@@ -19,7 +19,8 @@ When the Web server takes care of authentication it typically sets the
 ``REMOTE_USER`` environment variable for use in the underlying application.  In
 Django, ``REMOTE_USER`` is made available in the :attr:`request.META
 <django.http.HttpRequest.META>` attribute.  Django can be configured to make
-use of the ``REMOTE_USER`` value using the ``RemoteUserMiddleware`` and
+use of the ``REMOTE_USER`` value using the ``RemoteUserMiddleware``
+or ``PersistentRemoteUserMiddleware``, and
 :class:`~django.contrib.auth.backends.RemoteUserBackend` classes found in
 :mod:`django.contrib.auth`.
 
@@ -95,3 +96,25 @@ If your authentication mechanism uses a custom HTTP header and not
 If you need more control, you can create your own authentication backend
 that inherits from :class:`~django.contrib.auth.backends.RemoteUserBackend` and
 override one or more of its attributes and methods.
+
+.. _persistent-remote-user-middleware-howto:
+
+Using ``REMOTE_USER`` on login pages only
+=========================================
+
+.. versionadded:: 1.9
+
+The ``RemoteUserMiddleware`` authentication middleware assumes that the HTTP
+request header ``REMOTE_USER`` is present with all authenticated requests. That
+might be expected and practical when Basic HTTP Auth with ``htpasswd`` or other
+simple mechanisms are used, but with Negotiate (GSSAPI/Kerberos) or other
+resource intensive authentication methods, the authentication in the front-end
+HTTP server is usually only set up for one or a few login URLs, and after
+successful authentication, the application is supposed to maintain the
+authenticated session itself.
+
+:class:`~django.contrib.auth.middleware.PersistentRemoteUserMiddleware`
+provides support for this use case. It will maintain the authenticated session
+until explicit logout by the user. The class can be used as a drop-in
+replacement of :class:`~django.contrib.auth.middleware.RemoteUserMiddleware`
+in the documentation above.