fixed #10809 -- add a mod_wsgi authentication handler

Thanks to baumer1122 for the suggestion and initial 
patch and David Fischer for the contributions and
long term patch maintenance and docs.

docs/howto/deployment/wsgi/apache-auth.txt

@@ -0,0 +1,122 @@
+=========================================================
+Authenticating against Django's user database from Apache
+=========================================================
+
+Since keeping multiple authentication databases in sync is a common problem when
+dealing with Apache, you can configure Apache to authenticate against Django's
+:doc:`authentication system </topics/auth>` directly. This requires Apache
+version >= 2.2 and mod_wsgi >= 2.0. For example, you could:
+
+* Serve static/media files directly from Apache only to authenticated users.
+
+* Authenticate access to a Subversion_ repository against Django users with
+  a certain permission.
+
+* Allow certain users to connect to a WebDAV share created with mod_dav_.
+
+.. _Subversion: http://subversion.tigris.org/
+.. _mod_dav: http://httpd.apache.org/docs/2.2/mod/mod_dav.html
+
+Authentication with mod_wsgi
+============================
+
+Make sure that mod_wsgi is installed and activated and that you have
+followed the steps to setup
+:doc:`Apache with mod_wsgi </howto/deployment/wsgi/modwsgi>`
+
+Next, edit your Apache configuration to add a location that you want
+only authenticated users to be able to view:
+
+.. code-block:: apache
+
+    WSGIScriptAlias / /path/to/mysite/config/mysite.wsgi
+
+    WSGIProcessGroup %{GLOBAL}
+    WSGIApplicationGroup django
+
+    <Location "/secret">
+        AuthType Basic
+        AuthName "Top Secret"
+        Require valid-user
+        AuthBasicProvider wsgi
+        WSGIAuthUserScript /path/to/mysite/config/mysite.wsgi
+    </Location>
+
+The ``WSGIAuthUserScript`` directive tells mod_wsgi to execute the
+``check_password`` function in specified wsgi script, passing the user name and
+password that it receives from the prompt. In this example, the
+``WSGIAuthUserScript`` is the same as the ``WSGIScriptAlias`` that defines your
+application :doc:`that is created by django-admin.py startproject
+</howto/deployment/wsgi/index>`.
+
+.. admonition:: Using Apache 2.2 with authentication
+
+    Make sure that ``mod_auth_basic`` and ``mod_authz_user`` are loaded.
+
+    These might be compiled statically into Apache, or you might need to use
+    LoadModule to load them dynamically in your ``httpd.conf``:
+
+    .. code-block:: apache
+
+        LoadModule auth_basic_module modules/mod_auth_basic.so
+        LoadModule authz_user_module modules/mod_authz_user.so
+
+Finally, edit your WSGI script ``mysite.wsgi`` to tie Apache's
+authentication to your site's authentication mechanisms by importing the
+check_user function:
+
+.. code-block:: python
+
+    import os
+    import sys
+
+    os.environ['DJANGO_SETTINGS_MODULE'] = 'mysite.settings'
+
+    from django.contrib.auth.handlers.modwsgi import check_user
+
+    from django.core.handlers.wsgi import WSGIHandler
+    application = WSGIHandler()
+
+
+Requests beginning with ``/secret/`` will now require a user to authenticate.
+
+The mod_wsgi `access control mechanisms documentation`_ provides additional
+details and information about alternative methods of authentication.
+
+.. _access control mechanisms documentation: http://code.google.com/p/modwsgi/wiki/AccessControlMechanisms
+
+Authorization with mod_wsgi and Django groups
+---------------------------------------------
+
+mod_wsgi also provides functionality to restrict a particular location to
+members of a group.
+
+In this case, the Apache configuration should look like this:
+
+.. code-block:: apache
+
+    WSGIScriptAlias / /path/to/mysite/config/mysite.wsgi
+
+    WSGIProcessGroup %{GLOBAL}
+    WSGIApplicationGroup django
+
+    <Location "/secret">
+        AuthType Basic
+        AuthName "Top Secret"
+        AuthBasicProvider wsgi
+        WSGIAuthUserScript /path/to/mysite/config/mysite.wsgi
+        WSGIAuthGroupScript /path/to/mysite/config/mysite.wsgi
+        Require group secret-agents
+        Require valid-user
+    </Location>
+
+To support the ``WSGIAuthGroupScript`` directive, the same WSGI script
+``mysite.wsgi`` must also import the ``groups_for_user`` function which
+returns a list groups the given user belongs to.
+
+.. code-block:: python
+
+    from django.contrib.auth.handlers.modwsgi import check_user, groups_for_user
+
+Requests for ``/secret/`` will now also require user to be a member of the
+"secret-agents" group.