1 ====================================

     2 Authentication using ``REMOTE_USER``

     3 ====================================

     4 

     5 .. currentmodule:: django.contrib.auth.backends

     6 

     7 This document describes how to make use of external authentication sources

     8 (where the Web server sets the ``REMOTE_USER`` environment variable) in your

     9 Django applications.  This type of authentication solution is typically seen on

    10 intranet sites, with single sign-on solutions such as IIS and Integrated

    11 Windows 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 

    20 When the Web server takes care of authentication it typically sets the

    21 ``REMOTE_USER`` environment variable for use in the underlying application.  In

    22 Django, ``REMOTE_USER`` is made available in the :attr:`request.META

    23 <django.http.HttpRequest.META>` attribute.  Django can be configured to make

    24 use of the ``REMOTE_USER`` value using the ``RemoteUserMiddleware`` and

    25 ``RemoteUserBackend`` classes found in :mod:`django.contrib.auth`.

    26 

    27 Configuration

    28 =============

    29 

    30 First, 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 

    42 Next, you must replace the :class:`~django.contrib.auth.backends.ModelBackend`

    43 with ``RemoteUserBackend`` in the :setting:`AUTHENTICATION_BACKENDS` setting::

    44 

    45     AUTHENTICATION_BACKENDS = (

    46         'django.contrib.auth.backends.RemoteUserBackend',

    47     )

    48 

    49 With this setup, ``RemoteUserMiddleware`` will detect the username in

    50 ``request.META['REMOTE_USER']`` and will authenticate and auto-login that user

    51 using 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 

    58 If 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 

    73 If you need more control, you can create your own authentication backend

    74 that inherits from ``RemoteUserBackend`` and overrides certain parts:

    75 

    76 Attributes

    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 

    85 Methods

    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.