/docs/howto/auth-remote-user.txt
Plain Text | 100 lines | 74 code | 26 blank | 0 comment | 0 complexity | 6704e6d563bd5a417f25b88e9c89bf59 MD5 | raw file
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.