REMOTE_USER
¶This document describes how to make use of external authentication sources
(where the Web server sets the REMOTE_USER
environment variable) in your
Django applications. This type of authentication solution is typically seen on
intranet sites, with single sign-on solutions such as IIS and Integrated
Windows Authentication or Apache and mod_authnz_ldap, CAS, Cosign,
WebAuth, mod_auth_sspi, etc.
When the Web server takes care of authentication it typically sets the
REMOTE_USER
environment variable for use in the underlying application. In
Django, REMOTE_USER
is made available in the request.META
attribute. Django can be configured to make
use of the REMOTE_USER
value using the RemoteUserMiddleware
and
RemoteUserBackend
classes found in django.contrib.auth
.
First, you must add the
django.contrib.auth.middleware.RemoteUserMiddleware
to the
MIDDLEWARE_CLASSES
setting after the
django.contrib.auth.middleware.AuthenticationMiddleware
:
MIDDLEWARE_CLASSES = (
...
'django.contrib.auth.middleware.AuthenticationMiddleware',
'django.contrib.auth.middleware.RemoteUserMiddleware',
...
)
Next, you must replace the ModelBackend
with RemoteUserBackend
in the AUTHENTICATION_BACKENDS
setting:
AUTHENTICATION_BACKENDS = (
'django.contrib.auth.backends.RemoteUserBackend',
)
With this setup, RemoteUserMiddleware
will detect the username in
request.META['REMOTE_USER']
and will authenticate and auto-login that user
using the RemoteUserBackend
.
Note
Since the RemoteUserBackend
inherits from ModelBackend
, you will
still have all of the same permissions checking that is implemented in
ModelBackend
.
If your authentication mechanism uses a custom HTTP header and not
REMOTE_USER
, you can subclass RemoteUserMiddleware
and set the
header
attribute to the desired request.META
key. For example:
from django.contrib.auth.middleware import RemoteUserMiddleware
class CustomHeaderMiddleware(RemoteUserMiddleware):
header = 'HTTP_AUTHUSER'
RemoteUserBackend
¶django.contrib.auth.backends.
RemoteUserBackend
¶If you need more control, you can create your own authentication backend
that inherits from RemoteUserBackend
and overrides certain parts:
RemoteUserBackend.
clean_username
(username)¶Performs any cleaning on the username
(e.g. stripping LDAP DN
information) prior to using it to get or create a
User
object. Returns the cleaned
username.
RemoteUserBackend.
configure_user
(user)¶Configures a newly created user. This method is called immediately after a new user is created, and can be used to perform custom setup actions, such as setting the user’s groups based on attributes in an LDAP directory. Returns the user object.
Jul 07, 2017