Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

file 102 lines (75 sloc) 3.825 kb
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102
.. _howto-auth-remote-user:

====================================
Authentication using ``REMOTE_USER``
====================================

.. currentmodule:: django.contrib.backends

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.

.. _mod_authnz_ldap: http://httpd.apache.org/docs/2.2/mod/mod_authnz_ldap.html
.. _CAS: http://www.jasig.org/cas
.. _Cosign: http://weblogin.org
.. _WebAuth: http://www.stanford.edu/services/webauth/
.. _mod_auth_sspi: http://sourceforge.net/projects/mod-auth-sspi

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 :attr:`request.META
<django.http.HttpRequest.META>` attribute. Django can be configured to make
use of the ``REMOTE_USER`` value using the ``RemoteUserMiddleware`` and
``RemoteUserBackend`` classes found in :mod:`django.contrib.auth`.

Configuration
=============

First, you must add the
:class:`django.contrib.auth.middleware.RemoteUserMiddleware` to the
:setting:`MIDDLEWARE_CLASSES` setting **after** the
:class:`django.contrib.auth.middleware.AuthenticationMiddleware`::

    MIDDLEWARE_CLASSES = (
        ...
        'django.contrib.auth.middleware.AuthenticationMiddleware',
        'django.contrib.auth.middleware.RemoteUserMiddleware',
        ...
        )

Next, you must replace the :class:`~django.contrib.auth.backends.ModelBackend`
with ``RemoteUserBackend`` in the :setting:`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.backends.RemoteUserBackend

If you need more control, you can create your own authentication backend
that inherits from ``RemoteUserBackend`` and overrides certain parts:

Attributes
~~~~~~~~~~

.. attribute:: RemoteUserBackend.create_unknown_user

    ``True`` or ``False``. Determines whether or not a
    :class:`~django.contrib.auth.models.User` object is created if not already
    in the database. Defaults to ``True``.

Methods
~~~~~~~

.. method:: 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
   :class:`~django.contrib.auth.models.User` object. Returns the cleaned
   username.

.. method:: 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.
Something went wrong with that request. Please try again.