Debian Codegraph @

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

raw
1 ==============================================================
2 How to authenticate against Django's user database from Apache
3 ==============================================================
4
5 Since keeping multiple authentication databases in sync is a common problem when
6 dealing with Apache, you can configure Apache to authenticate against Django's
7 :doc:`authentication system </topics/auth/index>` directly. This requires Apache
8 version >= 2.2 and mod_wsgi >= 2.0. For example, you could:
9
10 * Serve static/media files directly from Apache only to authenticated users.
11
12 * Authenticate access to a Subversion_ repository against Django users with
13 a certain permission.
14
15 * Allow certain users to connect to a WebDAV share created with mod_dav_.
16
17 .. note::
18 If you have installed a :ref:`custom user model <auth-custom-user>` and
19 want to use this default auth handler, it must support an ``is_active``
20 attribute. If you want to use group based authorization, your custom user
21 must have a relation named 'groups', referring to a related object that has
22 a 'name' field. You can also specify your own custom mod_wsgi
23 auth handler if your custom cannot conform to these requirements.
24
25 .. _Subversion: https://subversion.apache.org/
26 .. _mod_dav: https://httpd.apache.org/docs/2.2/mod/mod_dav.html
27
28 Authentication with ``mod_wsgi``
29 ================================
30
31 .. note::
32
33 The use of ``WSGIApplicationGroup %{GLOBAL}`` in the configurations below
34 presumes that your Apache instance is running only one Django application.
35 If you are running more than one Django application, please refer to the
36 `Defining Application Groups`_ section of the mod_wsgi docs for more
37 information about this setting.
38
39 Make sure that mod_wsgi is installed and activated and that you have
40 followed the steps to set up :doc:`Apache with mod_wsgi
41 </howto/deployment/wsgi/modwsgi>`.
42
43 Next, edit your Apache configuration to add a location that you want
44 only authenticated users to be able to view:
45
46 .. code-block:: apache
47
48 WSGIScriptAlias / /path/to/mysite.com/mysite/wsgi.py
49 WSGIPythonPath /path/to/mysite.com
50
51 WSGIProcessGroup %{GLOBAL}
52 WSGIApplicationGroup %{GLOBAL}
53
54 <Location "/secret">
55 AuthType Basic
56 AuthName "Top Secret"
57 Require valid-user
58 AuthBasicProvider wsgi
59 WSGIAuthUserScript /path/to/mysite.com/mysite/wsgi.py
60 </Location>
61
62 The ``WSGIAuthUserScript`` directive tells mod_wsgi to execute the
63 ``check_password`` function in specified wsgi script, passing the user name and
64 password that it receives from the prompt. In this example, the
65 ``WSGIAuthUserScript`` is the same as the ``WSGIScriptAlias`` that defines your
66 application :doc:`that is created by django-admin startproject
67 </howto/deployment/wsgi/index>`.
68
69 .. admonition:: Using Apache 2.2 with authentication
70
71 Make sure that ``mod_auth_basic`` and ``mod_authz_user`` are loaded.
72
73 These might be compiled statically into Apache, or you might need to use
74 LoadModule to load them dynamically in your ``httpd.conf``:
75
76 .. code-block:: apache
77
78 LoadModule auth_basic_module modules/mod_auth_basic.so
79 LoadModule authz_user_module modules/mod_authz_user.so
80
81 Finally, edit your WSGI script ``mysite.wsgi`` to tie Apache's authentication
82 to your site's authentication mechanisms by importing the ``check_password``
83 function::
84
85 import os
86
87 os.environ["DJANGO_SETTINGS_MODULE"] = "mysite.settings"
88
89 from django.contrib.auth.handlers.modwsgi import check_password
90
91 from django.core.handlers.wsgi import WSGIHandler
92
93 application = WSGIHandler()
94
95
96 Requests beginning with ``/secret/`` will now require a user to authenticate.
97
98 The mod_wsgi `access control mechanisms documentation`_ provides additional
99 details and information about alternative methods of authentication.
100
101 .. _Defining Application Groups: https://modwsgi.readthedocs.io/en/develop/user-guides/configuration-guidelines.html#defining-application-groups
102 .. _access control mechanisms documentation: https://modwsgi.readthedocs.io/en/develop/user-guides/access-control-mechanisms.html
103
104 Authorization with ``mod_wsgi`` and Django groups
105 -------------------------------------------------
106
107 mod_wsgi also provides functionality to restrict a particular location to
108 members of a group.
109
110 In this case, the Apache configuration should look like this:
111
112 .. code-block:: apache
113
114 WSGIScriptAlias / /path/to/mysite.com/mysite/wsgi.py
115
116 WSGIProcessGroup %{GLOBAL}
117 WSGIApplicationGroup %{GLOBAL}
118
119 <Location "/secret">
120 AuthType Basic
121 AuthName "Top Secret"
122 AuthBasicProvider wsgi
123 WSGIAuthUserScript /path/to/mysite.com/mysite/wsgi.py
124 WSGIAuthGroupScript /path/to/mysite.com/mysite/wsgi.py
125 Require group secret-agents
126 Require valid-user
127 </Location>
128
129 To support the ``WSGIAuthGroupScript`` directive, the same WSGI script
130 ``mysite.wsgi`` must also import the ``groups_for_user`` function which
131 returns a list groups the given user belongs to.
132
133 .. code-block:: python
134
135 from django.contrib.auth.handlers.modwsgi import check_password, groups_for_user
136
137 Requests for ``/secret/`` will now also require user to be a member of the
138 "secret-agents" group.