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