Ticket #689: 689.4.diff

django/contrib/auth/backends.py

@@ -78 +78 @@
             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):
+        """
+        Cleans the passed username to remove any extraneous text, and returns
+        the cleaned username.
+
+        By default, this method returns the passed username unmodified.
+        Override this method if you need to do special things with the
+        username, like stripping @realm or cleaning something like
+        cn=user,dc=domain.
+        """
+        return username
+
+    def configure_user(self, user):
+        """
+        Configures a user after creation and returns the updated user.
+
+        By default, this method returns the passed user unmodified.  Override
+        this method if you would like to do additional setup on the user that
+        was just created, such as set groups based on attributes in an LDAP
+        directory.
+        """
+        return user

django/contrib/auth/middleware.py

@@ +1 @@
+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 +9 @@
             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 +1 @@
 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

@@ +1 @@
+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'
+    known_user = 'knownuser'
+
+    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='knownuser')
+        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='knownuser2')
+        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):
+
+    backend =\
+        'django.contrib.auth.tests.remote_user.CustomRemoteUserBackend'
+    known_user = 'knownuser@example.com'
+
+    def test_clean_username(self):
+        """
+        The strings passed in REMOTE_USER should be cleaned and the known users
+        should not have been configured with an email address.
+        """
+        User.objects.create(username='knownuser')
+        User.objects.create(username='knownuser2')
+        num_users = User.objects.count()
+
+        response = self.client.get('/', REMOTE_USER='knownuser@abc.com')
+        self.assertEqual(response.context['user'].username, 'knownuser')
+        self.assertEqual(response.context['user'].email, '')
+        self.assertEqual(User.objects.count(), num_users)
+
+        response = self.client.get('/', REMOTE_USER='knownuser2@abc.com')
+        self.assertEqual(response.context['user'].username, 'knownuser2')
+        self.assertEqual(response.context['user'].email, '')
+        self.assertEqual(User.objects.count(), num_users)
+
+    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/ref/authbackends.txt

@@ +1 @@
+.. _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 <topics-auth-remote-user>`
+    documentation.

docs/ref/index.txt

@@ -5 +5 @@
 
 .. toctree::
    :maxdepth: 1
-   
+
+   authbackends
    contrib/index
    databases
    django-admin
@@ -19 +20 @@
    signals
    templates/index
    unicode
-   
- No newline at end of file

docs/topics/auth-remote-user.txt

@@ +1 @@
+.. _topics-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)
+
+   Clean unwanted text from the passed username.  This is useful if the
+   username includes unwanted text, such extra LDAP DN information.  This
+   method needs to return the cleaned username.
+
+.. method:: RemoteUserBackend.configure_user(user)
+
+   Configure a newly created user.  This method is called immediately after a
+   new user is created, and can be used to perform custom setup actions for the
+   user.  This methods needs to return the user object.

docs/topics/auth.txt

@@ -1263 +1263 @@
 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

@@ -17 +17 @@
    files
    testing
    auth
+   auth-remote-user
    cache
    email
    i18n