granicus.if.org Git - apache/blob - docs/manual/mod/mod_authz_dbd.html.en

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