| 1 |
========================================= |
| 2 |
How to authenticate using ``REMOTE_USER`` |
| 3 |
========================================= |
| 4 |
|
| 5 |
This document describes how to make use of external authentication sources |
| 6 |
(where the web server sets the ``REMOTE_USER`` environment variable) in your |
| 7 |
Django applications. This type of authentication solution is typically seen on |
| 8 |
intranet sites, with single sign-on solutions such as IIS and Integrated |
| 9 |
Windows Authentication or Apache and `mod_authnz_ldap`_, `CAS`_, `WebAuth`_, |
| 10 |
`mod_auth_sspi`_, etc. |
| 11 |
|
| 12 |
.. _mod_authnz_ldap: https://httpd.apache.org/docs/current/mod/mod_authnz_ldap.html |
| 13 |
.. _CAS: https://www.apereo.org/projects/cas |
| 14 |
.. _WebAuth: https://uit.stanford.edu/service/authentication |
| 15 |
.. _mod_auth_sspi: https://sourceforge.net/projects/mod-auth-sspi |
| 16 |
|
| 17 |
When the web server takes care of authentication it typically sets the |
| 18 |
``REMOTE_USER`` environment variable for use in the underlying application. In |
| 19 |
Django, ``REMOTE_USER`` is made available in the :attr:`request.META |
| 20 |
<django.http.HttpRequest.META>` attribute. Django can be configured to make |
| 21 |
use of the ``REMOTE_USER`` value using the ``RemoteUserMiddleware`` |
| 22 |
or ``PersistentRemoteUserMiddleware``, and |
| 23 |
:class:`~django.contrib.auth.backends.RemoteUserBackend` classes found in |
| 24 |
:mod:`django.contrib.auth`. |
| 25 |
|
| 26 |
Configuration |
| 27 |
============= |
| 28 |
|
| 29 |
First, you must add the |
| 30 |
:class:`django.contrib.auth.middleware.RemoteUserMiddleware` to the |
| 31 |
:setting:`MIDDLEWARE` setting **after** the |
| 32 |
:class:`django.contrib.auth.middleware.AuthenticationMiddleware`:: |
| 33 |
|
| 34 |
MIDDLEWARE = [ |
| 35 |
"...", |
| 36 |
"django.contrib.auth.middleware.AuthenticationMiddleware", |
| 37 |
"django.contrib.auth.middleware.RemoteUserMiddleware", |
| 38 |
"...", |
| 39 |
] |
| 40 |
|
| 41 |
Next, you must replace the :class:`~django.contrib.auth.backends.ModelBackend` |
| 42 |
with :class:`~django.contrib.auth.backends.RemoteUserBackend` in the |
| 43 |
:setting:`AUTHENTICATION_BACKENDS` setting:: |
| 44 |
|
| 45 |
AUTHENTICATION_BACKENDS = [ |
| 46 |
"django.contrib.auth.backends.RemoteUserBackend", |
| 47 |
] |
| 48 |
|
| 49 |
With this setup, ``RemoteUserMiddleware`` will detect the username in |
| 50 |
``request.META['REMOTE_USER']`` and will authenticate and auto-login that user |
| 51 |
using the :class:`~django.contrib.auth.backends.RemoteUserBackend`. |
| 52 |
|
| 53 |
Be aware that this particular setup disables authentication with the default |
| 54 |
``ModelBackend``. This means that if the ``REMOTE_USER`` value is not set |
| 55 |
then the user is unable to log in, even using Django's admin interface. |
| 56 |
Adding ``'django.contrib.auth.backends.ModelBackend'`` to the |
| 57 |
``AUTHENTICATION_BACKENDS`` list will use ``ModelBackend`` as a fallback |
| 58 |
if ``REMOTE_USER`` is absent, which will solve these issues. |
| 59 |
|
| 60 |
Django's user management, such as the views in ``contrib.admin`` and |
| 61 |
the :djadmin:`createsuperuser` management command, doesn't integrate with |
| 62 |
remote users. These interfaces work with users stored in the database |
| 63 |
regardless of ``AUTHENTICATION_BACKENDS``. |
| 64 |
|
| 65 |
.. note:: |
| 66 |
|
| 67 |
Since the ``RemoteUserBackend`` inherits from ``ModelBackend``, you will |
| 68 |
still have all of the same permissions checking that is implemented in |
| 69 |
``ModelBackend``. |
| 70 |
|
| 71 |
Users with :attr:`is_active=False |
| 72 |
<django.contrib.auth.models.User.is_active>` won't be allowed to |
| 73 |
authenticate. Use |
| 74 |
:class:`~django.contrib.auth.backends.AllowAllUsersRemoteUserBackend` if |
| 75 |
you want to allow them to. |
| 76 |
|
| 77 |
If your authentication mechanism uses a custom HTTP header and not |
| 78 |
``REMOTE_USER``, you can subclass ``RemoteUserMiddleware`` and set the |
| 79 |
``header`` attribute to the desired ``request.META`` key. For example: |
| 80 |
|
| 81 |
.. code-block:: python |
| 82 |
:caption: ``mysite/middleware.py`` |
| 83 |
|
| 84 |
from django.contrib.auth.middleware import RemoteUserMiddleware |
| 85 |
|
| 86 |
|
| 87 |
class CustomHeaderRemoteUserMiddleware(RemoteUserMiddleware): |
| 88 |
header = "HTTP_AUTHUSER" |
| 89 |
|
| 90 |
This custom middleware is then used in the :setting:`MIDDLEWARE` setting |
| 91 |
instead of :class:`django.contrib.auth.middleware.RemoteUserMiddleware`:: |
| 92 |
|
| 93 |
MIDDLEWARE = [ |
| 94 |
"...", |
| 95 |
"django.contrib.auth.middleware.AuthenticationMiddleware", |
| 96 |
"mysite.middleware.CustomHeaderRemoteUserMiddleware", |
| 97 |
"...", |
| 98 |
] |
| 99 |
|
| 100 |
.. warning:: |
| 101 |
|
| 102 |
Be very careful if using a ``RemoteUserMiddleware`` subclass with a custom |
| 103 |
HTTP header. You must be sure that your front-end web server always sets or |
| 104 |
strips that header based on the appropriate authentication checks, never |
| 105 |
permitting an end-user to submit a fake (or "spoofed") header value. Since |
| 106 |
the HTTP headers ``X-Auth-User`` and ``X-Auth_User`` (for example) both |
| 107 |
normalize to the ``HTTP_X_AUTH_USER`` key in ``request.META``, you must |
| 108 |
also check that your web server doesn't allow a spoofed header using |
| 109 |
underscores in place of dashes. |
| 110 |
|
| 111 |
This warning doesn't apply to ``RemoteUserMiddleware`` in its default |
| 112 |
configuration with ``header = 'REMOTE_USER'``, since a key that doesn't |
| 113 |
start with ``HTTP_`` in ``request.META`` can only be set by your WSGI |
| 114 |
server, not directly from an HTTP request header. |
| 115 |
|
| 116 |
If you need more control, you can create your own authentication backend |
| 117 |
that inherits from :class:`~django.contrib.auth.backends.RemoteUserBackend` and |
| 118 |
override one or more of its attributes and methods. |
| 119 |
|
| 120 |
.. _persistent-remote-user-middleware-howto: |
| 121 |
|
| 122 |
Using ``REMOTE_USER`` on login pages only |
| 123 |
========================================= |
| 124 |
|
| 125 |
The ``RemoteUserMiddleware`` authentication middleware assumes that the HTTP |
| 126 |
request header ``REMOTE_USER`` is present with all authenticated requests. That |
| 127 |
might be expected and practical when Basic HTTP Auth with ``htpasswd`` or |
| 128 |
similar mechanisms are used, but with Negotiate (GSSAPI/Kerberos) or other |
| 129 |
resource intensive authentication methods, the authentication in the front-end |
| 130 |
HTTP server is usually only set up for one or a few login URLs, and after |
| 131 |
successful authentication, the application is supposed to maintain the |
| 132 |
authenticated session itself. |
| 133 |
|
| 134 |
:class:`~django.contrib.auth.middleware.PersistentRemoteUserMiddleware` |
| 135 |
provides support for this use case. It will maintain the authenticated session |
| 136 |
until explicit logout by the user. The class can be used as a drop-in |
| 137 |
replacement of :class:`~django.contrib.auth.middleware.RemoteUserMiddleware` |
| 138 |
in the documentation above. |