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