Fixed #689 -- Added a middleware and authentication backend to contrib.auth for supporting external authentication solutions. Thanks to all who contributed to this patch, including Ian Holsman, garthk, Koen Biermans, Marc Fargas, ekarulf, and Ramiro Morales.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@10063 bcc190cf-cafb-0310-a4f2-bffc1f526a37

7 files changed, 154 insertions, 12 deletions

diff --git a/docs/howto/auth-remote-user.txt b/docs/howto/auth-remote-user.txt
new file mode 100644
index 0000000000..aa39b1fba4
--- /dev/null
+++ b/docs/howto/auth-remote-user.txt
@@ -0,0 +1,100 @@
+.. _howto-auth-remote-user:
+
+====================================
+Authentication using ``REMOTE_USER``
+====================================
+
+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.ja-sig.org/products/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.contirb.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.
diff --git a/docs/howto/index.txt b/docs/howto/index.txt
index 4fdae82750..1a27a2ebac 100644
--- a/docs/howto/index.txt
+++ b/docs/howto/index.txt
@@ -10,8 +10,9 @@ you quickly accomplish common tasks.
 
 .. toctree::
    :maxdepth: 1
-   
+
    apache-auth
+   auth-remote-user
    custom-management-commands
    custom-model-fields
    custom-template-tags
@@ -30,5 +31,5 @@ you quickly accomplish common tasks.
     The `Django community aggregator`_, where we aggregate content from the
     global Django community. Many writers in the aggregator write this sort of
     how-to material.
-    
-    .. _django community aggregator: http://www.djangoproject.com/community/
\ No newline at end of file
+
+    .. _django community aggregator: http://www.djangoproject.com/community/
diff --git a/docs/ref/authbackends.txt b/docs/ref/authbackends.txt
new file mode 100644
index 0000000000..941152733a
--- /dev/null
+++ b/docs/ref/authbackends.txt
@@ -0,0 +1,37 @@
+.. _ref-authentication-backends:
+
+==========================================
+Built-in authentication backends reference
+==========================================
+
+.. module:: django.contrib.auth.backends
+   :synopsis: Django's built-in authentication backend classes.
+
+This document details the authentication backends that come with Django. For
+information on how how to use them and how to write your own authentication
+backends, see the :ref:`Other authentication sources section
+<authentication-backends>` of the :ref:`User authentication guide
+<topics-auth>`.
+
+
+Available authentication backends
+=================================
+
+The following backends are available in :mod:`django.contrib.auth.backends`:
+
+.. class:: ModelBackend
+
+    This is the default authentication backend used by Django.  It
+    authenticates using usernames and passwords stored in the the
+    :class:`~django.contrib.auth.models.User` model.
+
+
+.. class:: RemoteUserBackend
+
+    .. versionadded:: 1.1
+
+    Use this backend to take advantage of external-to-Django-handled
+    authentication.  It authenticates using usernames passed in
+    :attr:`request.META['REMOTE_USER'] <django.http.HttpRequest.META>`.  See
+    the :ref:`Authenticating against REMOTE_USER <howto-auth-remote-user>`
+    documentation.
diff --git a/docs/ref/index.txt b/docs/ref/index.txt
index c54cd20954..3ffa1fcce1 100644
--- a/docs/ref/index.txt
+++ b/docs/ref/index.txt
@@ -5,7 +5,8 @@ API Reference
 
 .. toctree::
    :maxdepth: 1
-   
+
+   authbackends
    contrib/index
    databases
    django-admin
@@ -19,4 +20,3 @@ API Reference
    signals
    templates/index
    unicode
-   
\ No newline at end of file
diff --git a/docs/ref/request-response.txt b/docs/ref/request-response.txt
index fcf4523218..cd0edc063c 100644
--- a/docs/ref/request-response.txt
+++ b/docs/ref/request-response.txt
@@ -138,6 +138,7 @@ All attributes except ``session`` should be considered read-only.
         * ``QUERY_STRING`` -- The query string, as a single (unparsed) string.
         * ``REMOTE_ADDR`` -- The IP address of the client.
         * ``REMOTE_HOST`` -- The hostname of the client.
+        * ``REMOTE_USER`` -- The user authenticated by the web server, if any.
         * ``REQUEST_METHOD`` -- A string such as ``"GET"`` or ``"POST"``.
         * ``SERVER_NAME`` -- The hostname of the server.
         * ``SERVER_PORT`` -- The port of the server.
@@ -294,7 +295,7 @@ a subclass of dictionary. Exceptions are outlined here:
     Just like the standard dictionary ``setdefault()`` method, except it uses
     ``__setitem__`` internally.
 
-.. method:: QueryDict.update(other_dict) 
+.. method:: QueryDict.update(other_dict)
 
     Takes either a ``QueryDict`` or standard dictionary. Just like the standard
     dictionary ``update()`` method, except it *appends* to the current
@@ -357,11 +358,11 @@ In addition, ``QueryDict`` has the following methods:
 
     Like :meth:`items()`, except it includes all values, as a list, for each
     member of the dictionary. For example::
-    
+
          >>> q = QueryDict('a=1&a=2&a=3')
          >>> q.lists()
          [('a', ['1', '2', '3'])]
-    
+
 .. method:: QueryDict.urlencode()
 
     Returns a string of the data in query-string format.
@@ -452,7 +453,7 @@ Methods
 -------
 
 .. method:: HttpResponse.__init__(content='', mimetype=None, status=200, content_type=DEFAULT_CONTENT_TYPE)
-    
+
     Instantiates an ``HttpResponse`` object with the given page content (a
     string) and MIME type. The ``DEFAULT_CONTENT_TYPE`` is ``'text/html'``.
 
diff --git a/docs/topics/auth.txt b/docs/topics/auth.txt
index 9759ed821d..47405dd875 100644
--- a/docs/topics/auth.txt
+++ b/docs/topics/auth.txt
@@ -1263,10 +1263,13 @@ administrator and the users themselves if users had separate accounts in LDAP
 and the Django-based applications.
 
 So, to handle situations like this, the Django authentication system lets you
-plug in another authentication sources. You can override Django's default
+plug in other authentication sources. You can override Django's default
 database-based scheme, or you can use the default system in tandem with other
 systems.
 
+See the :ref:`authentication backend reference <ref-authentication-backends>`
+for information on the authentication backends included with Django.
+
 Specifying authentication backends
 ----------------------------------
 
diff --git a/docs/topics/index.txt b/docs/topics/index.txt
index 5d83980837..d4a32ab6ce 100644
--- a/docs/topics/index.txt
+++ b/docs/topics/index.txt
@@ -7,7 +7,7 @@ Introductions to all the key parts of Django you'll need to know:
 
 .. toctree::
    :maxdepth: 1
-   
+
    install
    db/index
    http/index
@@ -23,4 +23,4 @@ Introductions to all the key parts of Django you'll need to know:
    pagination
    serialization
    settings
-   signals
\ No newline at end of file
+   signals