From 64dfc41d563afe3c66402f7906c902800d0a3ac6 Mon Sep 17 00:00:00 2001 From: Jacob Walls Date: Tue, 31 Mar 2026 15:43:18 -0400 Subject: [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. --- docs/howto/auth-remote-user.txt | 29 ++++++++++++++++++----------- docs/internals/security.txt | 6 ++++++ docs/ref/middleware.txt | 2 +- 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 -------------------------- -- cgit v1.3