Newer
Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head>
<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type" />
<!--
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
This file is generated from xml source: DO NOT EDIT
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
-->
<title>mod_authz_dbd - Apache HTTP Server Version 2.4</title>
<link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
<link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
<link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link rel="stylesheet" type="text/css" href="../style/css/prettify.css" />
<script src="../style/scripts/prettify.min.js" type="text/javascript">
</script>
<link href="../images/favicon.ico" rel="shortcut icon" /></head>
<body>
<div id="page-header">
<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
<p class="apache">Apache HTTP Server Version 2.4</p>
<img alt="" src="../images/feather.png" /></div>
<div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div>
<div id="path">
<a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="../">Version 2.4</a> > <a href="./">Modules</a></div>
<div id="page-content">
<div id="preamble"><h1>Apache Module mod_authz_dbd</h1>
<div class="toplang">
<p><span>Available Languages: </span><a href="../en/mod/mod_authz_dbd.html" title="English"> en </a> |
<a href="../fr/mod/mod_authz_dbd.html" hreflang="fr" rel="alternate" title="Franais"> fr </a></p>
</div>
<table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Group Authorization and Login using SQL</td></tr>
<tr><th><a href="module-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="module-dict.html#ModuleIdentifier">ModuleIdentifier:</a></th><td>authz_dbd_module</td></tr>
<tr><th><a href="module-dict.html#SourceFile">SourceFile:</a></th><td>mod_authz_dbd.c</td></tr>
<tr><th><a href="module-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.4 and later</td></tr></table>
<h3>Summary</h3>
<p>This module provides authorization capabilities so that
authenticated users can be allowed or denied access to portions
of the web site by group membership. Similar functionality is
provided by <code class="module"><a href="../mod/mod_authz_groupfile.html">mod_authz_groupfile</a></code> and
<code class="module"><a href="../mod/mod_authz_dbm.html">mod_authz_dbm</a></code>, with the exception that
this module queries a SQL database to determine whether a
user is a member of a group.</p>
<p>This module can also provide database-backed user login/logout
capabilities. These are likely to be of most value when used
in conjunction with <code class="module"><a href="../mod/mod_authn_dbd.html">mod_authn_dbd</a></code>.</p>
<p>This module relies on <code class="module"><a href="../mod/mod_dbd.html">mod_dbd</a></code> to specify
the backend database driver and connection parameters, and
manage the database connections.</p>
</div>
<div id="quickview"><a href="https://www.apache.org/foundation/contributing.html" class="badge"><img src="https://www.apache.org/images/SupportApache-small.png" alt="Support Apache!" /></a><h3>Topics</h3>
<ul id="topics">
<li><img alt="" src="../images/down.gif" /> <a href="#requiredirectives">The Require Directives</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#login">Database Login</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#client">Client Login integration</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#example">Configuration example</a></li>
</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#authzdbdlogintoreferer">AuthzDBDLoginToReferer</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#authzdbdquery">AuthzDBDQuery</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#authzdbdredirectquery">AuthzDBDRedirectQuery</a></li>
</ul>
<h3>Bugfix checklist</h3><ul class="seealso"><li><a href="https://www.apache.org/dist/httpd/CHANGES_2.4">httpd changelog</a></li><li><a href="https://bz.apache.org/bugzilla/buglist.cgi?bug_status=__open__&list_id=144532&product=Apache%20httpd-2&query_format=specific&order=changeddate%20DESC%2Cpriority%2Cbug_severity&component=mod_authz_dbd">Known issues</a></li><li><a href="https://bz.apache.org/bugzilla/enter_bug.cgi?product=Apache%20httpd-2&component=mod_authz_dbd">Report a bug</a></li></ul><h3>See also</h3>
<ul class="seealso">
<li><code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code></li>
<li>
<code class="directive"><a href="../mod/mod_authn_dbd.html#authdbduserpwquery">AuthDBDUserPWQuery</a></code>
</li>
<li><code class="directive"><a href="../mod/mod_dbd.html#dbdriver">DBDriver</a></code></li>
<li><code class="directive"><a href="../mod/mod_dbd.html#dbdparams">DBDParams</a></code></li>
<li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="requiredirectives" id="requiredirectives">The Require Directives</a></h2>
<p>Apache's <code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code>
directives are used during the authorization phase to ensure that
a user is allowed to access a resource. mod_authz_dbd extends the
authorization types with <code>dbd-group</code>, <code>dbd-login</code> and
<code>dbd-logout</code>.</p>
<p>Since v2.4.8, <a href="../expr.html">expressions</a> are supported
within the DBD require directives.</p>
<h3><a name="reqgroup" id="reqgroup">Require dbd-group</a></h3>
<p>This directive specifies group membership that is required for the
user to gain access.</p>
<pre class="prettyprint lang-config">Require dbd-group team
AuthzDBDQuery "SELECT group FROM authz WHERE user = %s"</pre>
<h3><a name="reqlogin" id="reqlogin">Require dbd-login</a></h3>
<p>This directive specifies a query to be run indicating the user
has logged in.</p>
<pre class="prettyprint lang-config">Require dbd-login
AuthzDBDQuery "UPDATE authn SET login = 'true' WHERE user = %s"</pre>
<h3><a name="reqlogout" id="reqlogout">Require dbd-logout</a></h3>
<p>This directive specifies a query to be run indicating the user
has logged out.</p>
<pre class="prettyprint lang-config">Require dbd-logout
AuthzDBDQuery "UPDATE authn SET login = 'false' WHERE user = %s"</pre>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="login" id="login">Database Login</a></h2>
<p>
In addition to the standard authorization function of checking group
membership, this module can also provide server-side user session
management via database-backed login/logout capabilities.
Specifically, it can update a user's session status in the database
whenever the user visits designated URLs (subject of course to users
supplying the necessary credentials).</p>
<p>This works by defining two special
<code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code> types:
<code>Require dbd-login</code> and <code>Require dbd-logout</code>.
For usage details, see the configuration example below.</p>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="client" id="client">Client Login integration</a></h2>
<p>Some administrators may wish to implement client-side session
management that works in concert with the server-side login/logout
capabilities offered by this module, for example, by setting or unsetting
an HTTP cookie or other such token when a user logs in or out.</p>
<p>To support such integration, <code class="module"><a href="../mod/mod_authz_dbd.html">mod_authz_dbd</a></code> exports an
optional hook that will be run whenever a user's status is updated in
the database. Other session management modules can then use the hook
to implement functions that start and end client-side sessions.</p>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="example" id="example">Configuration example</a></h2>
<pre class="prettyprint lang-config"># mod_dbd configuration
DBDriver pgsql
DBDParams "dbname=apacheauth user=apache pass=xxxxxx"
DBDMin 4
DBDKeep 8
DBDMax 20
DBDExptime 300
<Directory "/usr/www/my.site/team-private/">
# mod_authn_core and mod_auth_basic configuration
# for mod_authn_dbd
AuthType Basic
AuthName Team
AuthBasicProvider dbd
# mod_authn_dbd SQL query to authenticate a logged-in user
AuthDBDUserPWQuery \
"SELECT password FROM authn WHERE user = %s AND login = 'true'"
# mod_authz_core configuration for mod_authz_dbd
Require dbd-group team
# mod_authz_dbd configuration
AuthzDBDQuery "SELECT group FROM authz WHERE user = %s"
# when a user fails to be authenticated or authorized,
# invite them to login; this page should provide a link
# to /team-private/login.html
ErrorDocument 401 "/login-info.html"
<Files "login.html">
# don't require user to already be logged in!
AuthDBDUserPWQuery "SELECT password FROM authn WHERE user = %s"
# dbd-login action executes a statement to log user in
Require dbd-login
AuthzDBDQuery "UPDATE authn SET login = 'true' WHERE user = %s"
# return user to referring page (if any) after
# successful login
AuthzDBDLoginToReferer On
</Files>
<Files "logout.html">
# dbd-logout action executes a statement to log user out
Require dbd-logout
AuthzDBDQuery "UPDATE authn SET login = 'false' WHERE user = %s"
</Files>
</Directory></pre>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="AuthzDBDLoginToReferer" id="AuthzDBDLoginToReferer">AuthzDBDLoginToReferer</a> <a name="authzdbdlogintoreferer" id="authzdbdlogintoreferer">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Determines whether to redirect the Client to the Referring
page on successful login or logout if a <code>Referer</code> request
header is present</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthzDBDLoginToReferer On|Off</code></td></tr>
<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>AuthzDBDLoginToReferer Off</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authz_dbd</td></tr>
</table>
<p>In conjunction with <code>Require dbd-login</code> or
<code>Require dbd-logout</code>, this provides the option to
redirect the client back to the Referring page (the URL in
the <code>Referer</code> HTTP request header, if present).
When there is no <code>Referer</code> header,
<code>AuthzDBDLoginToReferer On</code> will be ignored.</p>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="AuthzDBDQuery" id="AuthzDBDQuery">AuthzDBDQuery</a> <a name="authzdbdquery" id="authzdbdquery">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Specify the SQL Query for the required operation</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthzDBDQuery <var>query</var></code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authz_dbd</td></tr>
</table>
<p>The <code class="directive">AuthzDBDQuery</code> specifies an SQL
query to run. The purpose of the query depends on the
<code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code> directive in
effect.</p>
<ul>
<li>When used with a <code>Require dbd-group</code> directive,
it specifies a query to look up groups for the current user. This is
the standard functionality of other authorization modules such as
<code class="module"><a href="../mod/mod_authz_groupfile.html">mod_authz_groupfile</a></code> and <code class="module"><a href="../mod/mod_authz_dbm.html">mod_authz_dbm</a></code>.
The first column value of each row returned by the query statement
should be a string containing a group name. Zero, one, or more rows
may be returned.
<pre class="prettyprint lang-config">Require dbd-group
AuthzDBDQuery "SELECT group FROM groups WHERE user = %s"</pre>
</li>
<li>When used with a <code>Require dbd-login</code> or
<code>Require dbd-logout</code> directive, it will never deny access,
but will instead execute a SQL statement designed to log the user
in or out. The user must already be authenticated with
<code class="module"><a href="../mod/mod_authn_dbd.html">mod_authn_dbd</a></code>.
<pre class="prettyprint lang-config">Require dbd-login
AuthzDBDQuery "UPDATE authn SET login = 'true' WHERE user = %s"</pre>
</li>
</ul>
<p>In all cases, the user's ID will be passed as a single string
parameter when the SQL query is executed. It may be referenced within
the query statement using a <code>%s</code> format specifier.</p>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="AuthzDBDRedirectQuery" id="AuthzDBDRedirectQuery">AuthzDBDRedirectQuery</a> <a name="authzdbdredirectquery" id="authzdbdredirectquery">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Specify a query to look up a login page for the user</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthzDBDRedirectQuery <var>query</var></code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authz_dbd</td></tr>
</table>
<p>Specifies an optional SQL query to use after successful login
(or logout) to redirect the user to a URL, which may be
specific to the user. The user's ID will be passed as a single string
parameter when the SQL query is executed. It may be referenced within
the query statement using a <code>%s</code> format specifier.</p>
<pre class="prettyprint lang-config">AuthzDBDRedirectQuery "SELECT userpage FROM userpages WHERE user = %s"</pre>
<p>The first column value of the first row returned by the query
statement should be a string containing a URL to which to redirect
the client. Subsequent rows will be ignored. If no rows are returned,
the client will not be redirected.</p>
<p>Note that <code class="directive">AuthzDBDLoginToReferer</code> takes
precedence if both are set.</p>
</div>
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_authz_dbd.html" title="English"> en </a> |
<a href="../fr/mod/mod_authz_dbd.html" hreflang="fr" rel="alternate" title="Franais"> fr </a></p>
</div><div class="top"><a href="#page-header"><img src="../images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div>
<script type="text/javascript"><!--//--><![CDATA[//><!--
var comments_shortname = 'httpd';
var comments_identifier = 'http://httpd.apache.org/docs/2.4/mod/mod_authz_dbd.html';
(function(w, d) {
if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
d.write('<div id="comments_thread"><\/div>');
var s = d.createElement('script');
s.type = 'text/javascript';
s.async = true;
s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
(d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
}
else {
d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
}
})(window, document);
//--><!]]></script></div><div id="footer">
<p class="apache">Copyright 2017 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!--
if (typeof(prettyPrint) !== 'undefined') {
prettyPrint();
}
//--><!]]></script>
</body></html>