Django-1.2.1/docs/howto/apache-auth.txt

   1 .. _howto-apache-auth:
   2
   3 =========================================================
   4 Authenticating against Django's user database from Apache
   5 =========================================================
   6
   7 Since keeping multiple authentication databases in sync is a common problem when
   8 dealing with Apache, you can configuring Apache to authenticate against Django's
   9 :ref:`authentication system <topics-auth>` directly. For example, you
  10 could:
  11
  12     * Serve static/media files directly from Apache only to authenticated users.
  13
  14     * Authenticate access to a Subversion_ repository against Django users with
  15       a certain permission.
  16
  17     * Allow certain users to connect to a WebDAV share created with mod_dav_.
  18
  19 .. _Subversion: http://subversion.tigris.org/
  20 .. _mod_dav: http://httpd.apache.org/docs/2.0/mod/mod_dav.html
  21
  22 Configuring Apache
  23 ==================
  24
  25 To check against Django's authorization database from a Apache configuration
  26 file, you'll need to use mod_python's ``PythonAuthenHandler`` directive along
  27 with the standard ``Auth*`` and ``Require`` directives:
  28
  29 .. code-block:: apache
  30
  31     <Location /example/>
  32         AuthType Basic
  33         AuthName "example.com"
  34         Require valid-user
  35
  36         SetEnv DJANGO_SETTINGS_MODULE mysite.settings
  37         PythonAuthenHandler django.contrib.auth.handlers.modpython
  38     </Location>
  39
  40 .. admonition:: Using the authentication handler with Apache 2.2
  41
  42     If you're using Apache 2.2, you'll need to take a couple extra steps.
  43
  44     You'll need to ensure that ``mod_auth_basic`` and ``mod_authz_user``
  45     are loaded. These might be compiled statically into Apache, or you might
  46     need to use ``LoadModule`` to load them dynamically (as shown in the
  47     example at the bottom of this note).
  48
  49     You'll also need to insert configuration directives that prevent Apache
  50     from trying to use other authentication modules, as well as specifying
  51     the ``AuthUserFile`` directive and pointing it to ``/dev/null``. Depending
  52     on which other authentication modules you have loaded, you might need one
  53     or more of the following directives:
  54
  55     .. code-block:: apache
  56
  57         AuthBasicAuthoritative Off
  58         AuthDefaultAuthoritative Off
  59         AuthzLDAPAuthoritative Off
  60         AuthzDBMAuthoritative Off
  61         AuthzDefaultAuthoritative Off
  62         AuthzGroupFileAuthoritative Off
  63         AuthzOwnerAuthoritative Off
  64         AuthzUserAuthoritative Off
  65
  66     A complete configuration, with differences between Apache 2.0 and
  67     Apache 2.2 marked in bold, would look something like:
  68
  69     .. parsed-literal::
  70
  71         **LoadModule auth_basic_module modules/mod_auth_basic.so**
  72         **LoadModule authz_user_module modules/mod_authz_user.so**
  73
  74         ...
  75
  76         <Location /example/>
  77             AuthType Basic
  78             AuthName "example.com"
  79             **AuthUserFile /dev/null**
  80             **AuthBasicAuthoritative Off**
  81             Require valid-user
  82
  83             SetEnv DJANGO_SETTINGS_MODULE mysite.settings
  84             PythonAuthenHandler django.contrib.auth.handlers.modpython
  85         </Location>
  86
  87 By default, the authentication handler will limit access to the ``/example/``
  88 location to users marked as staff members.  You can use a set of
  89 ``PythonOption`` directives to modify this behavior:
  90
  91     ================================  =========================================
  92     ``PythonOption``                  Explanation
  93     ================================  =========================================
  94     ``DjangoRequireStaffStatus``      If set to ``on`` only "staff" users (i.e.
  95                                       those with the ``is_staff`` flag set)
  96                                       will be allowed.
  97
  98                                       Defaults to ``on``.
  99
 100     ``DjangoRequireSuperuserStatus``  If set to ``on`` only superusers (i.e.
 101                                       those with the ``is_superuser`` flag set)
 102                                       will be allowed.
 103
 104                                       Defaults to ``off``.
 105
 106     ``DjangoPermissionName``          The name of a permission to require for
 107                                       access. See :ref:`custom permissions
 108                                       <custom-permissions>` for more
 109                                       information.
 110
 111                                       By default no specific permission will be
 112                                       required.
 113     ================================  =========================================
 114
 115 Note that sometimes ``SetEnv`` doesn't play well in this mod_python
 116 configuration, for reasons unknown. If you're having problems getting
 117 mod_python to recognize your ``DJANGO_SETTINGS_MODULE``, you can set it using
 118 ``PythonOption`` instead of ``SetEnv``. Therefore, these two Apache directives
 119 are equivalent::
 120
 121     SetEnv DJANGO_SETTINGS_MODULE mysite.settings
 122     PythonOption DJANGO_SETTINGS_MODULE mysite.settings