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