From b994387d8d9ff3b19d3ab04d3b4ac69d5dd68ea2 Mon Sep 17 00:00:00 2001 From: Gary Wilson Jr Date: Sun, 15 Mar 2009 05:54:28 +0000 Subject: 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 --- docs/howto/auth-remote-user.txt | 100 ++++++++++++++++++++++++++++++++++++++++ docs/howto/index.txt | 7 +-- 2 files changed, 104 insertions(+), 3 deletions(-) create mode 100644 docs/howto/auth-remote-user.txt (limited to 'docs/howto') 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 +` 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/ -- cgit v1.3