Authentication using 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
.
Configuration¶
-
class
django.contrib.auth.middleware.
RemoteUserMiddleware
¶
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
¶
-
class
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:
Attributes¶
Methods¶
-
RemoteUserBackend.
clean_username
(username)¶ Performs any cleaning on the
username
(e.g. stripping LDAP DN information) prior to using it to get or create aUser
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.