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

django/contrib/auth/backends.py

@@ -78,3 +78,64 @@ class ModelBackend(object):
             return User.objects.get(pk=user_id)
         except User.DoesNotExist:
             return None
+
+
+class RemoteUserBackend(ModelBackend):
+    """
+    This backend is to be used in conjunction with the ``RemoteUserMiddleware``
+    found in the middleware module of this package, and is used when the server
+    is handling authentication outside of Django.
+
+    By default, the ``authenticate`` method creates ``User`` objects for
+    usernames that don't already exist in the database.  Subclasses can disable
+    this behavior by setting the ``create_unknown_user`` attribute to
+    ``False``.
+    """
+
+    # Create a User object if not already in the database?
+    create_unknown_user = True
+
+    def authenticate(self, remote_user):
+        """
+        The username passed as ``remote_user`` is considered trusted.  This
+        method simply returns the ``User`` object with the given username,
+        creating a new ``User`` object if ``create_unknown_user`` is ``True``.
+
+        Returns None if ``create_unknown_user`` is ``False`` and a ``User``
+        object with the given username is not found in the database.
+        """
+        if not remote_user:
+            return
+        user = None
+        username = self.clean_username(remote_user)
+
+        # Note that this could be accomplished in one try-except clause, but
+        # instead we use get_or_create when creating unknown users since it has
+        # built-in safeguards for multiple threads.
+        if self.create_unknown_user:
+            user, created = User.objects.get_or_create(username=username)
+            if created:
+                user = self.configure_user(user)
+        else:
+            try:
+                user = User.objects.get(username=username)
+            except User.DoesNotExist:
+                pass
+        return user
+
+    def clean_username(self, username):
+        """
+        Performs any cleaning on the "username" prior to using it to get or
+        create the user object.  Returns the cleaned username.
+
+        By default, returns the username unchanged.
+        """
+        return username
+
+    def configure_user(self, user):
+        """
+        Configures a user after creation and returns the updated user.
+
+        By default, returns the user unmodified.
+        """
+        return user

django/contrib/auth/middleware.py

@@ -1,3 +1,7 @@
+from django.contrib import auth
+from django.core.exceptions import ImproperlyConfigured
+
+
 class LazyUser(object):
     def __get__(self, request, obj_type=None):
         if not hasattr(request, '_cached_user'):
@@ -5,8 +9,73 @@ class LazyUser(object):
             request._cached_user = get_user(request)
         return request._cached_user
 
+
 class AuthenticationMiddleware(object):
     def process_request(self, request):
         assert hasattr(request, 'session'), "The Django authentication middleware requires session middleware to be installed. Edit your MIDDLEWARE_CLASSES setting to insert 'django.contrib.sessions.middleware.SessionMiddleware'."
         request.__class__.user = LazyUser()
         return None
+
+
+class RemoteUserMiddleware(object):
+    """
+    Middleware for utilizing web-server-provided authentication.
+
+    If request.user is not authenticated, then this middleware attempts to
+    authenticate the username passed in the ``REMOTE_USER`` request header.
+    If authentication is successful, the user is automatically logged in to
+    persist the user in the session.
+
+    The header used is configurable and defaults to ``REMOTE_USER``.  Subclass
+    this class and change the ``header`` attribute if you need to use a
+    different header.
+    """
+
+    # Name of request header to grab username from.  This will be the key as
+    # used in the request.META dictionary, i.e. the normalization of headers to
+    # all uppercase and the addition of "HTTP_" prefix apply.
+    header = "REMOTE_USER"
+
+    def process_request(self, request):
+        # AuthenticationMiddleware is required so that request.user exists.
+        if not hasattr(request, 'user'):
+            raise ImproperlyConfigured(
+                "The Django remote user auth middleware requires the"
+                " authentication middleware to be installed.  Edit your"
+                " MIDDLEWARE_CLASSES setting to insert"
+                " 'django.contrib.auth.middleware.AuthenticationMiddleware'"
+                " before the RemoteUserMiddleware class.")
+        try:
+            username = request.META[self.header]
+        except KeyError:
+            # If specified header doesn't exist then return (leaving
+            # request.user set to AnonymousUser by the
+            # AuthenticationMiddleware).
+            return
+        # If the user is already authenticated and that user is the user we are
+        # getting passed in the headers, then the correct user is already
+        # persisted in the session and we don't need to continue.
+        if request.user.is_authenticated():
+            if request.user.username == self.clean_username(username, request):
+                return
+        # We are seeing this user for the first time in this session, attempt
+        # to authenticate the user.
+        user = auth.authenticate(remote_user=username)
+        if user:
+            # User is valid.  Set request.user and persist user in the session
+            # by logging the user in.
+            request.user = user
+            auth.login(request, user)
+
+    def clean_username(self, username, request):
+        """
+        Allows the backend to clean the username, if the backend defines a
+        clean_username method.
+        """
+        backend_str = request.session[auth.BACKEND_SESSION_KEY]
+        backend = auth.load_backend(backend_str)
+        try:
+            username = backend.clean_username(username)
+        except AttributeError: # Backend has no clean_username method.
+            pass
+        return username

django/contrib/auth/tests/__init__.py

@@ -1,6 +1,9 @@
 from django.contrib.auth.tests.basic import BASIC_TESTS
-from django.contrib.auth.tests.views import PasswordResetTest, ChangePasswordTest
+from django.contrib.auth.tests.views \
+        import PasswordResetTest, ChangePasswordTest
 from django.contrib.auth.tests.forms import FORM_TESTS
+from django.contrib.auth.tests.remote_user \
+        import RemoteUserTest, RemoteUserNoCreateTest, RemoteUserCustomTest
 from django.contrib.auth.tests.tokens import TOKEN_GENERATOR_TESTS
 
 # The password for the fixture data users is 'password'

django/contrib/auth/tests/remote_user.py

@@ -0,0 +1,169 @@
+from datetime import datetime
+
+from django.conf import settings
+from django.contrib.auth.backends import RemoteUserBackend
+from django.contrib.auth.models import AnonymousUser, User
+from django.test import TestCase
+
+
+class RemoteUserTest(TestCase):
+
+    middleware = 'django.contrib.auth.middleware.RemoteUserMiddleware'
+    backend = 'django.contrib.auth.backends.RemoteUserBackend'
+
+    # Usernames to be passed in REMOTE_USER for the test_known_user test case.
+    known_user = 'knownuser'
+    known_user2 = 'knownuser2'
+
+    def setUp(self):
+        self.curr_middleware = settings.MIDDLEWARE_CLASSES
+        self.curr_auth = settings.AUTHENTICATION_BACKENDS
+        settings.MIDDLEWARE_CLASSES += (self.middleware,)
+        settings.AUTHENTICATION_BACKENDS = (self.backend,)
+
+    def test_no_remote_user(self):
+        """
+        Tests requests where no remote user is specified and insures that no
+        users get created.
+        """
+        num_users = User.objects.count()
+
+        response = self.client.get('/')
+        self.assert_(isinstance(response.context['user'], AnonymousUser))
+        self.assertEqual(User.objects.count(), num_users)
+
+        response = self.client.get('/', REMOTE_USER=None)
+        self.assert_(isinstance(response.context['user'], AnonymousUser))
+        self.assertEqual(User.objects.count(), num_users)
+
+        response = self.client.get('/', REMOTE_USER='')
+        self.assert_(isinstance(response.context['user'], AnonymousUser))
+        self.assertEqual(User.objects.count(), num_users)
+
+    def test_unknown_user(self):
+        """
+        Tests the case where the username passed in the header does not exist
+        as a User.
+        """
+        num_users = User.objects.count()
+        response = self.client.get('/', REMOTE_USER='newuser')
+        self.assertEqual(response.context['user'].username, 'newuser')
+        self.assertEqual(User.objects.count(), num_users + 1)
+        User.objects.get(username='newuser')
+
+        # Another request with same user should not create any new users.
+        response = self.client.get('/', REMOTE_USER='newuser')
+        self.assertEqual(User.objects.count(), num_users + 1)
+
+    def test_known_user(self):
+        """
+        Tests the case where the username passed in the header is a valid User.
+        """
+        User.objects.create(username='knownuser')
+        User.objects.create(username='knownuser2')
+        num_users = User.objects.count()
+        response = self.client.get('/', REMOTE_USER=self.known_user)
+        self.assertEqual(response.context['user'].username, 'knownuser')
+        self.assertEqual(User.objects.count(), num_users)
+        # Test that a different user passed in the headers causes the new user
+        # to be logged in.
+        response = self.client.get('/', REMOTE_USER=self.known_user2)
+        self.assertEqual(response.context['user'].username, 'knownuser2')
+        self.assertEqual(User.objects.count(), num_users)
+
+    def test_last_login(self):
+        """
+        Tests that a user's last_login is set the first time they make a
+        request but not updated in subsequent requests with the same session.
+        """
+        user = User.objects.create(username='knownuser')
+        # Set last_login to something so we can determine if it changes.
+        default_login = datetime(2000, 1, 1)
+        user.last_login = default_login
+        user.save()
+
+        response = self.client.get('/', REMOTE_USER=self.known_user)
+        self.assertNotEqual(default_login, response.context['user'].last_login)
+
+        user = User.objects.get(username='knownuser')
+        user.last_login = default_login
+        user.save()
+        response = self.client.get('/', REMOTE_USER=self.known_user)
+        self.assertEqual(default_login, response.context['user'].last_login)
+
+    def tearDown(self):
+        """Restores settings to avoid breaking other tests."""
+        settings.MIDDLEWARE_CLASSES = self.curr_middleware
+        settings.AUTHENTICATION_BACKENDS = self.curr_auth
+
+
+class RemoteUserNoCreateBackend(RemoteUserBackend):
+    """Backend that doesn't create unknown users."""
+    create_unknown_user = False
+
+
+class RemoteUserNoCreateTest(RemoteUserTest):
+    """
+    Contains the same tests as RemoteUserTest, but using a custom auth backend
+    class that doesn't create unknown users.
+    """
+
+    backend =\
+        'django.contrib.auth.tests.remote_user.RemoteUserNoCreateBackend'
+
+    def test_unknown_user(self):
+        num_users = User.objects.count()
+        response = self.client.get('/', REMOTE_USER='newuser')
+        self.assert_(isinstance(response.context['user'], AnonymousUser))
+        self.assertEqual(User.objects.count(), num_users)
+
+
+class CustomRemoteUserBackend(RemoteUserBackend):
+    """
+    Backend that overrides RemoteUserBackend methods.
+    """
+
+    def clean_username(self, username):
+        """
+        Grabs username before the @ character.
+        """
+        return username.split('@')[0]
+
+    def configure_user(self, user):
+        """
+        Sets user's email address.
+        """
+        user.email = 'user@example.com'
+        user.save()
+        return user
+
+
+class RemoteUserCustomTest(RemoteUserTest):
+    """
+    Tests a custom RemoteUserBackend subclass that overrides the clean_username
+    and configure_user methods.
+    """
+
+    backend =\
+        'django.contrib.auth.tests.remote_user.CustomRemoteUserBackend'
+    # REMOTE_USER strings with e-mail addresses for the custom backend to
+    # clean.
+    known_user = 'knownuser@example.com'
+    known_user2 = 'knownuser2@example.com'
+
+    def test_known_user(self):
+        """
+        The strings passed in REMOTE_USER should be cleaned and the known users
+        should not have been configured with an email address.
+        """
+        super(RemoteUserCustomTest, self).test_known_user()
+        self.assertEqual(User.objects.get(username='knownuser').email, '')
+        self.assertEqual(User.objects.get(username='knownuser2').email, '')
+
+    def test_unknown_user(self):
+        """
+        The unknown user created should be configured with an email address.
+        """
+        super(RemoteUserCustomTest, self).test_unknown_user()
+        newuser = User.objects.get(username='newuser')
+        self.assertEqual(newuser.email, 'user@example.com')

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.

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/
+    .. _django community aggregator: http://www.djangoproject.com/community/

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.

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
-   

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

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

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
+   signals