Authentication using REMOTE_USER. Django Software

CHAPTER

4

“How-to” guides

Here you’ll find short answers to “How do I....?” types of questions. These how-to guides don’t cover topics in depth

– you’ll find that material in the

Using Django

and the

API Reference . However, these guides will help you quickly

accomplish common tasks.

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 or

PersistentRemoteUserMiddleware

, and

RemoteUserBackend

classes found in

django.contrib.

auth

.

Configuration

First, you must add the

django.contrib.auth.middleware.RemoteUserMiddleware

to the

MIDDLEWARE

setting after the

django.contrib.auth.middleware.AuthenticationMiddleware

:

MIDDLEWARE = [

'...' ,

'django.contrib.auth.middleware.AuthenticationMiddleware' ,

'django.contrib.auth.middleware.RemoteUserMiddleware' ,

'...' ,

]

Next, you must replace the

ModelBackend

with

RemoteUserBackend

in the

AUTHENTICATION_BACKENDS

setting:

531

Django Documentation, Release 2.0.dev20170914110741

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

.

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

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

Users with

is_active=False

won’t be allowed to authenticate. Use

AllowAllUsersRemoteUserBackend

if you want to allow them to.

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'

Warning: Be very careful if using a RemoteUserMiddleware subclass with a custom HTTP header. You must be sure that your front-end web server always sets or strips that header based on the appropriate authentication checks, never permitting an end-user to submit a fake (or “spoofed”) header value. Since the HTTP headers X-Auth-User and X-Auth_User (for example) both normalize to the HTTP_X_AUTH_USER key in request.META

, you must also check that your web server doesn’t allow a spoofed header using underscores in place of dashes.

This warning doesn’t apply to RemoteUserMiddleware in its default configuration with header =

'REMOTE_USER'

, since a key that doesn’t start with HTTP_ in request.META can only be set by your WSGI server, not directly from an HTTP request header.

If you need more control, you can create your own authentication backend that inherits from

RemoteUserBackend

and override one or more of its attributes and methods.

Using REMOTE_USER on login pages only

The RemoteUserMiddleware authentication middleware assumes that the HTTP request header REMOTE_USER is present with all authenticated requests.

That might be expected and practical when Basic HTTP Auth with htpasswd or other simple mechanisms are used, but with Negotiate (GSSAPI/Kerberos) or other resource intensive authentication methods, the authentication in the front-end HTTP server is usually only set up for one or a few login URLs, and after successful authentication, the application is supposed to maintain the authenticated session itself.

532 Chapter 4. “How-to” guides