/docs/howto/auth-remote-user.txt

  1====================================
  2Authentication using ``REMOTE_USER``
  3====================================
  4
  5.. currentmodule:: django.contrib.auth.backends
  6
  7This document describes how to make use of external authentication sources
  8(where the Web server sets the ``REMOTE_USER`` environment variable) in your
  9Django applications.  This type of authentication solution is typically seen on
 10intranet sites, with single sign-on solutions such as IIS and Integrated
 11Windows Authentication or Apache and `mod_authnz_ldap`_, `CAS`_, `Cosign`_,
 12`WebAuth`_, `mod_auth_sspi`_, etc.
 13
 14.. _mod_authnz_ldap: http://httpd.apache.org/docs/2.2/mod/mod_authnz_ldap.html
 15.. _CAS: http://www.jasig.org/cas
 16.. _Cosign: http://weblogin.org
 17.. _WebAuth: http://www.stanford.edu/services/webauth/
 18.. _mod_auth_sspi: http://sourceforge.net/projects/mod-auth-sspi
 19
 20When the Web server takes care of authentication it typically sets the
 21``REMOTE_USER`` environment variable for use in the underlying application.  In
 22Django, ``REMOTE_USER`` is made available in the :attr:`request.META
 23<django.http.HttpRequest.META>` attribute.  Django can be configured to make
 24use of the ``REMOTE_USER`` value using the ``RemoteUserMiddleware`` and
 25``RemoteUserBackend`` classes found in :mod:`django.contrib.auth`.
 26
 27Configuration
 28=============
 29
 30First, you must add the
 31:class:`django.contrib.auth.middleware.RemoteUserMiddleware` to the
 32:setting:`MIDDLEWARE_CLASSES` setting **after** the
 33:class:`django.contrib.auth.middleware.AuthenticationMiddleware`::
 34
 35    MIDDLEWARE_CLASSES = (
 36        ...
 37        'django.contrib.auth.middleware.AuthenticationMiddleware',
 38        'django.contrib.auth.middleware.RemoteUserMiddleware',
 39        ...
 40        )
 41
 42Next, you must replace the :class:`~django.contrib.auth.backends.ModelBackend`
 43with ``RemoteUserBackend`` in the :setting:`AUTHENTICATION_BACKENDS` setting::
 44
 45    AUTHENTICATION_BACKENDS = (
 46        'django.contrib.auth.backends.RemoteUserBackend',
 47    )
 48
 49With this setup, ``RemoteUserMiddleware`` will detect the username in
 50``request.META['REMOTE_USER']`` and will authenticate and auto-login that user
 51using the ``RemoteUserBackend``.
 52
 53.. note::
 54   Since the ``RemoteUserBackend`` inherits from ``ModelBackend``, you will
 55   still have all of the same permissions checking that is implemented in
 56   ``ModelBackend``.
 57
 58If your authentication mechanism uses a custom HTTP header and not
 59``REMOTE_USER``, you can subclass ``RemoteUserMiddleware`` and set the
 60``header`` attribute to the desired ``request.META`` key.  For example::
 61
 62    from django.contrib.auth.middleware import RemoteUserMiddleware
 63
 64    class CustomHeaderMiddleware(RemoteUserMiddleware):
 65        header = 'HTTP_AUTHUSER'
 66
 67
 68``RemoteUserBackend``
 69=====================
 70
 71.. class:: django.contrib.auth.backends.RemoteUserBackend
 72
 73If you need more control, you can create your own authentication backend
 74that inherits from ``RemoteUserBackend`` and overrides certain parts:
 75
 76Attributes
 77~~~~~~~~~~
 78
 79.. attribute:: RemoteUserBackend.create_unknown_user
 80
 81    ``True`` or ``False``.  Determines whether or not a
 82    :class:`~django.contrib.auth.models.User` object is created if not already
 83    in the database.  Defaults to ``True``.
 84
 85Methods
 86~~~~~~~
 87
 88.. method:: RemoteUserBackend.clean_username(username)
 89
 90   Performs any cleaning on the ``username`` (e.g. stripping LDAP DN
 91   information) prior to using it to get or create a
 92   :class:`~django.contrib.auth.models.User` object.  Returns the cleaned
 93   username.
 94
 95.. method:: RemoteUserBackend.configure_user(user)
 96
 97   Configures a newly created user.  This method is called immediately after a
 98   new user is created, and can be used to perform custom setup actions, such
 99   as setting the user's groups based on attributes in an LDAP directory.
100   Returns the user object.