/docs/howto/apache-auth.txt

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