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

3 files changed, 36 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.
diff --git a/docs/ref/middleware.txt b/docs/ref/middleware.txt
index d256347577..733e701119 100644
--- a/docs/ref/middleware.txt
+++ b/docs/ref/middleware.txt
@@ -374,6 +374,14 @@ every incoming ``HttpRequest`` object. See :ref:`Authentication in Web requests
 Middleware for utilizing Web server provided authentication. See
 :doc:`/howto/auth-remote-user` for usage details.
 
+.. class:: PersistentRemoteUserMiddleware
+
+.. versionadded:: 1.9
+
+Middleware for utilizing Web server provided authentication when enabled only
+on the login page. See :ref:`persistent-remote-user-middleware-howto` for usage
+details.
+
 .. class:: SessionAuthenticationMiddleware
 
 Allows a user's sessions to be invalidated when their password changes. See
diff --git a/docs/releases/1.9.txt b/docs/releases/1.9.txt
index 3dc76dbd12..0b84b3c6d3 100644
--- a/docs/releases/1.9.txt
+++ b/docs/releases/1.9.txt
@@ -172,6 +172,10 @@ Minor features
   :func:`~django.contrib.auth.decorators.permission_required()` accepts all
   kinds of iterables, not only list and tuples.
 
+* The new :class:`~django.contrib.auth.middleware.PersistentRemoteUserMiddleware`
+  makes it possible to use ``REMOTE_USER`` for setups where the header is only
+  populated on login pages instead of every request in the session.
+
 :mod:`django.contrib.gis`
 ^^^^^^^^^^^^^^^^^^^^^^^^^^