[6.0.x] Fixed #36862 -- Doc'd the need for a proxy when deploying RemoteUserMiddleware under ASGI.

We have a flood of nuisance security reports describing ASGI deployments
using RemoteUserMiddleware without a fronting proxy, which is not
realistic.

Backport of 2ee757ee502d5663f932dc5c35175c39af4640ce from main.

3 files changed, 25 insertions, 12 deletions

diff --git a/docs/howto/auth-remote-user.txt b/docs/howto/auth-remote-user.txt
index 533f460e4a..fe48bb3dc8 100644
--- a/docs/howto/auth-remote-user.txt
+++ b/docs/howto/auth-remote-user.txt
@@ -99,19 +99,26 @@ instead of :class:`django.contrib.auth.middleware.RemoteUserMiddleware`::
 
 .. warning::
 
-    Be very careful if using a ``RemoteUserMiddleware`` subclass with a custom
-    HTTP header. You must be sure that your front-end web server always sets or
-    strips that header based on the appropriate authentication checks, never
-    permitting an end-user to submit a fake (or "spoofed") header value. Since
-    the HTTP headers ``X-Auth-User`` and ``X-Auth_User`` (for example) both
-    normalize to the ``HTTP_X_AUTH_USER`` key in ``request.META``, you must
-    also check that your web server doesn't allow a spoofed header using
+    ``RemoteUserMiddleware`` must not be deployed in configurations where a
+    client can supply the header. You must be sure that your web server or
+    reverse proxy always sets or strips that header based on the appropriate
+    authentication checks, never permitting an end user to submit a fake (or
+    "spoofed") header value. In particular, ASGI deployments cannot be exposed
+    directly to the internet (that is, without a reverse proxy) when using this
+    middleware.
+
+    Since the HTTP headers ``X-Auth-User`` and ``X-Auth_User`` (for example)
+    both normalize to the ``HTTP_X_AUTH_USER`` key in ``request.META``, you
+    must also check that your web server doesn't allow a spoofed header using
     underscores in place of dashes.
 
-    This warning doesn't apply to ``RemoteUserMiddleware`` in its default
-    configuration with ``header = 'REMOTE_USER'``, since a key that doesn't
-    start with ``HTTP_`` in ``request.META`` can only be set by your WSGI
-    or ASGI server, not directly from an HTTP request header.
+    Under WSGI, this warning doesn't apply to ``RemoteUserMiddleware`` in its
+    default configuration with ``header = "REMOTE_USER"``, since a key that
+    doesn't start with ``HTTP_`` in ``request.META`` can only be set by your
+    WSGI server, not directly from an HTTP request header. This warning *does*
+    apply by default on ASGI, because in the async path, the middleware
+    prepends ``HTTP_`` to the defined header name before looking it up in
+    ``request.META``.
 
 If you need more control, you can create your own authentication backend
 that inherits from :class:`~django.contrib.auth.backends.RemoteUserBackend` and
diff --git a/docs/internals/security.txt b/docs/internals/security.txt
index 300e0b9e6e..32705584a4 100644
--- a/docs/internals/security.txt
+++ b/docs/internals/security.txt
@@ -131,6 +131,12 @@ not been sanitized::
         q = MyModel.objects.extra(select={"id": query})
         return HttpResponse(q.values())
 
+Some HTTP headers must also be sanitized by a web server or fronting proxy
+before they can be used, such as ``Remote-User`` and ``X-Forwarded-*``. For
+instance, under ASGI, it is a deployment misconfiguration (rather than any flaw
+in Django) for Django to be the direct HTTP endpoint when
+:class:`~django.contrib.auth.middleware.RemoteUserMiddleware` is used.
+
 Request headers and URLs must be under 8K bytes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/ref/middleware.txt b/docs/ref/middleware.txt
index 29e8f7b941..9fdc54264c 100644
--- a/docs/ref/middleware.txt
+++ b/docs/ref/middleware.txt
@@ -580,7 +580,7 @@ Middleware for utilizing web server provided authentication. See
 
 Middleware for utilizing web server provided authentication when enabled only
 on the login page. See :ref:`persistent-remote-user-middleware-howto` for usage
-details.
+details, including security considerations.
 
 CSRF protection middleware
 --------------------------