granicus.if.org Git - apache/blob - docs/manual/mod/mod_authn_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_authn_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.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.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_authn_dbd</h1>
  26 <div class="toplang">
  27 <p><span>Available Languages: </span><a href="../en/mod/mod_authn_dbd.html" title="English">&nbsp;en&nbsp;</a></p>
  28 </div>
  29 <table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>User authentication using an SQL database</td></tr>
  30 <tr><th><a href="module-dict.html#Status">Status:</a></th><td>Extension</td></tr>
  31 <tr><th><a href="module-dict.html#ModuleIdentifier">Module Identifier:</a></th><td>authn_dbd_module</td></tr>
  32 <tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>mod_authn_dbd.c</td></tr>
  33 <tr><th><a href="module-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.1 and later</td></tr></table>
  34 <h3>Summary</h3>
  35
  36     <p>This module provides authentication front-ends such as
  37     <code class="module"><a href="../mod/mod_auth_digest.html">mod_auth_digest</a></code> and <code class="module"><a href="../mod/mod_auth_basic.html">mod_auth_basic</a></code>
  38     to authenticate users by looking up users in SQL tables.
  39     Similar functionality is provided by, for example,
  40     <code class="module"><a href="../mod/mod_authn_file.html">mod_authn_file</a></code>.</p>
  41     <p>This module relies on <code class="module"><a href="../mod/mod_dbd.html">mod_dbd</a></code> to specify
  42     the backend database driver and connection parameters, and
  43     manage the database connections.</p>
  44
  45     <p>When using <code class="module"><a href="../mod/mod_auth_basic.html">mod_auth_basic</a></code> or
  46     <code class="module"><a href="../mod/mod_auth_digest.html">mod_auth_digest</a></code>, this module is invoked via the
  47     <code class="directive"><a href="../mod/mod_auth_basic.html#authbasicprovider">AuthBasicProvider</a></code> or
  48     <code class="directive"><a href="../mod/mod_auth_digest.html#authdigestprovider">AuthDigestProvider</a></code>
  49     with the <code>dbd</code> value.</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="#authdbduserpwquery">AuthDBDUserPWQuery</a></li>
  54 <li><img alt="" src="../images/down.gif" /> <a href="#authdbduserrealmquery">AuthDBDUserRealmQuery</a></li>
  55 </ul>
  56 <h3>Topics</h3>
  57 <ul id="topics">
  58 <li><img alt="" src="../images/down.gif" /> <a href="#socache">Performance and Cacheing</a></li>
  59 <li><img alt="" src="../images/down.gif" /> <a href="#example">Configuration Example</a></li>
  60 <li><img alt="" src="../images/down.gif" /> <a href="#exposed">Exposing Login Information</a></li>
  61 </ul><h3>See also</h3>
  62 <ul class="seealso">
  63 <li><code class="directive"><a href="../mod/mod_authn_core.html#authname">AuthName</a></code></li>
  64 <li><code class="directive"><a href="../mod/mod_authn_core.html#authtype">AuthType</a></code></li>
  65 <li>
  66   <code class="directive"><a href="../mod/mod_auth_basic.html#authbasicprovider">AuthBasicProvider</a></code>
  67 </li>
  68 <li>
  69   <code class="directive"><a href="../mod/mod_auth_digest.html#authdigestprovider">AuthDigestProvider</a></code>
  70 </li>
  71 <li><code class="directive"><a href="../mod/mod_dbd.html#dbdriver">DBDriver</a></code></li>
  72 <li><code class="directive"><a href="../mod/mod_dbd.html#dbdparams">DBDParams</a></code></li>
  73 <li><a href="../misc/password_encryptions.html">Password Formats</a></li>
  74 </ul><ul class="seealso"><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="socache" id="socache">Performance and Cacheing</a></h2>
  78
  79 <p>Some users of DBD authentication in HTTPD 2.2 have reported that it
  80 imposes a problematic load on the database.  This is most likely where
  81 an HTML page contains hundreds of objects (e.g. images, scripts, etc)
  82 each of which requires authentication.  Users affected (or concerned)
  83 by this kind of problem should use <code class="module"><a href="../mod/mod_authn_socache.html">mod_authn_socache</a></code>
  84 to cache credentials and take most of the load off the database.</p>
  85 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  86 <div class="section">
  87 <h2><a name="example" id="example">Configuration Example</a></h2>
  88
  89 <p>This simple example shows use of this module in the context of
  90 the Authentication and DBD frameworks.</p>
  91 <pre class="prettyprint lang-config">
  92 # mod_dbd configuration
  93 # UPDATED to include authentication cacheing
  94 DBDriver pgsql
  95 DBDParams "dbname=apacheauth user=apache password=xxxxxx"
  96
  97 DBDMin  4
  98 DBDKeep 8
  99 DBDMax  20
 100 DBDExptime 300
 101
 102 &lt;Directory /usr/www/myhost/private&gt;
 103   # mod_authn_core and mod_auth_basic configuration
 104   # for mod_authn_dbd
 105   AuthType Basic
 106   AuthName "My Server"
 107
 108   # To cache credentials, put socache ahead of dbd here
 109   AuthBasicProvider socache dbd
 110
 111   # Also required for caching: tell the cache to cache dbd lookups!
 112   AuthnCacheProvideFor dbd
 113   AuthnCacheContext my-server
 114
 115   # mod_authz_core configuration
 116   Require valid-user
 117
 118   # mod_authn_dbd SQL query to authenticate a user
 119   AuthDBDUserPWQuery "SELECT password FROM authn WHERE user = %s"
 120 &lt;/Directory&gt;
 121 </pre>
 122
 123 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 124 <div class="section">
 125 <h2><a name="exposed" id="exposed">Exposing Login Information</a></h2>
 126
 127 <p>
 128 If httpd was built against <a class="glossarylink" href="../glossary.html#apr" title="see glossary">APR</a> version 1.3.0
 129 or higher, then whenever a query is made to the database server, all
 130 column values in the first row returned by the query are placed in the
 131 environment, using environment variables with the prefix "AUTHENTICATE_".
 132 </p>
 133 <p>If a database query for example returned the username, full name
 134 and telephone number of a user, a CGI program will have access to
 135 this information without the need to make a second independent database
 136 query to gather this additional information.</p>
 137 <p>This has the potential to dramatically simplify the coding and
 138 configuration required in some web applications.
 139 </p>
 140 </div>
 141 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 142 <div class="directive-section"><h2><a name="AuthDBDUserPWQuery" id="AuthDBDUserPWQuery">AuthDBDUserPWQuery</a> <a name="authdbduserpwquery" id="authdbduserpwquery">Directive</a></h2>
 143 <table class="directive">
 144 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>SQL query to look up a password for a user</td></tr>
 145 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthDBDUserPWQuery <var>query</var></code></td></tr>
 146 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory</td></tr>
 147 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 148 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authn_dbd</td></tr>
 149 </table>
 150     <p>The <code class="directive">AuthDBDUserPWQuery</code> specifies an
 151     SQL query to look up a password for a specified user.  The user's ID
 152     will be passed as a single string parameter when the SQL query is
 153     executed.  It may be referenced within the query statement using
 154     a <code>%s</code> format specifier.</p>
 155     <pre class="prettyprint lang-config">
 156 AuthDBDUserPWQuery "SELECT password FROM authn WHERE user = %s"
 157 </pre>
 158
 159     <p>The first column value of the first row returned by the query
 160     statement should be a string containing the encrypted password.
 161     Subsequent rows will be ignored.  If no rows are returned, the user
 162     will not be authenticated through <code class="module"><a href="../mod/mod_authn_dbd.html">mod_authn_dbd</a></code>.</p>
 163     <p>If httpd was built against <a class="glossarylink" href="../glossary.html#apr" title="see glossary">APR</a> version 1.3.0
 164     or higher, any additional column values in the first row returned by
 165     the query statement will be stored as environment variables with
 166     names of the form <code>AUTHENTICATE_<var>COLUMN</var></code>.
 167     </p>
 168     <p>The encrypted password format depends on which authentication
 169     frontend (e.g. <code class="module"><a href="../mod/mod_auth_basic.html">mod_auth_basic</a></code> or
 170     <code class="module"><a href="../mod/mod_auth_digest.html">mod_auth_digest</a></code>) is being used.  See <a href="../misc/password_encryptions.html">Password Formats</a> for
 171     more information.</p>
 172
 173 </div>
 174 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 175 <div class="directive-section"><h2><a name="AuthDBDUserRealmQuery" id="AuthDBDUserRealmQuery">AuthDBDUserRealmQuery</a> <a name="authdbduserrealmquery" id="authdbduserrealmquery">Directive</a></h2>
 176 <table class="directive">
 177 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>SQL query to look up a password hash for a user and realm.
 178 </td></tr>
 179 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthDBDUserRealmQuery <var>query</var></code></td></tr>
 180 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory</td></tr>
 181 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 182 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authn_dbd</td></tr>
 183 </table>
 184     <p>The <code class="directive">AuthDBDUserRealmQuery</code> specifies an
 185     SQL query to look up a password for a specified user and realm.
 186     The user's ID and the realm, in that order, will be passed as string
 187     parameters when the SQL query is executed.  They may be referenced
 188     within the query statement using <code>%s</code> format specifiers.</p>
 189     <pre class="prettyprint lang-config">
 190 AuthDBDUserRealmQuery "SELECT password FROM authn WHERE user = %s AND realm = %s"
 191 </pre>
 192
 193     <p>The first column value of the first row returned by the query
 194     statement should be a string containing the encrypted password.
 195     Subsequent rows will be ignored.  If no rows are returned, the user
 196     will not be authenticated through <code class="module"><a href="../mod/mod_authn_dbd.html">mod_authn_dbd</a></code>.</p>
 197     <p>If httpd was built against <a class="glossarylink" href="../glossary.html#apr" title="see glossary">APR</a> version 1.3.0
 198     or higher, any additional column values in the first row returned by
 199     the query statement will be stored as environment variables with
 200     names of the form <code>AUTHENTICATE_<var>COLUMN</var></code>.
 201     </p>
 202     <p>The encrypted password format depends on which authentication
 203     frontend (e.g. <code class="module"><a href="../mod/mod_auth_basic.html">mod_auth_basic</a></code> or
 204     <code class="module"><a href="../mod/mod_auth_digest.html">mod_auth_digest</a></code>) is being used.  See <a href="../misc/password_encryptions.html">Password Formats</a> for
 205     more information.</p>
 206
 207 </div>
 208 </div>
 209 <div class="bottomlang">
 210 <p><span>Available Languages: </span><a href="../en/mod/mod_authn_dbd.html" title="English">&nbsp;en&nbsp;</a></p>
 211 </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>
 212 <script type="text/javascript"><!--//--><![CDATA[//><!--
 213 var comments_shortname = 'httpd';
 214 var comments_identifier = 'http://httpd.apache.org/docs/trunk/mod/mod_authn_dbd.html';
 215 (function(w, d) {
 216     if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
 217         d.write('<div id="comments_thread"><\/div>');
 218         var s = d.createElement('script');
 219         s.type = 'text/javascript';
 220         s.async = true;
 221         s.src = 'https://c.apaste.info/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
 222         (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
 223     }
 224     else {
 225         d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
 226     }
 227 })(window, document);
 228 //--><!]]></script></div><div id="footer">
 229 <p class="apache">Copyright 2012 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>
 230 <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[//><!--
 231 if (typeof(prettyPrint) !== 'undefined') {
 232     prettyPrint();
 233 }
 234 //--><!]]></script>
 235 </body></html>