Debian Codegraph @

docs/howto/auth-remote-user.txt

raw
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.