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