[1.7.x] Fixed #24379 -- Documented that remote user example disables ModelBackend.

Backport of 6b28e957df364532109a1897c73a1fa8b1416bd4 from master

1 files changed, 12 insertions, 0 deletions

diff --git a/docs/howto/auth-remote-user.txt b/docs/howto/auth-remote-user.txt
index dc96a98bbc..8d1d44af1d 100644
--- a/docs/howto/auth-remote-user.txt
+++ b/docs/howto/auth-remote-user.txt
@@ -50,6 +50,18 @@ With this setup, ``RemoteUserMiddleware`` will detect the username in
 ``request.META['REMOTE_USER']`` and will authenticate and auto-login that user
 using the :class:`~django.contrib.auth.backends.RemoteUserBackend`.
 
+Be aware that this particular setup disables authentication with the default
+``ModelBackend``. This means that if the ``REMOTE_USER`` value is not set
+then the user is unable to log in, even using Django's admin interface.
+Adding ``'django.contrib.auth.backends.ModelBackend'`` to the
+``AUTHENTICATION_BACKENDS`` list will use ``ModelBackend`` as a fallback
+if ``REMOTE_USER`` is absent, which will solve these issues.
+
+Django's user management, such as the views in ``contrib.admin`` and
+the :djadmin:`createsuperuser` management command, doesn't integrate with
+remote users. These interfaces work with users stored in the database
+regardless of ``AUTHENTICATION_BACKENDS``.
+
 .. note::
    Since the ``RemoteUserBackend`` inherits from ``ModelBackend``, you will
    still have all of the same permissions checking that is implemented in