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