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