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
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">
15 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
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="<-" alt="<-" src="../images/left.gif" /></a></div>
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.5</a> > <a href="./">Modules</a></div>
24 <div id="page-content">
25 <div id="preamble"><h1>Apache Module mod_authn_dbd</h1>
27 <p><span>Available Languages: </span><a href="../en/mod/mod_authn_dbd.html" title="English"> en </a></p>
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>
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>
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>
51 <div id="quickview"><h3 class="directives">Directives</h3>
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>
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>
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>
66 <code class="directive"><a href="../mod/mod_auth_basic.html#authbasicprovider">AuthBasicProvider</a></code>
69 <code class="directive"><a href="../mod/mod_auth_digest.html#authdigestprovider">AuthDigestProvider</a></code>
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>
77 <h2><a name="socache" id="socache">Performance and Cacheing</a></h2>
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>
87 <h2><a name="example" id="example">Configuration Example</a></h2>
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
95 DBDParams "dbname=apacheauth user=apache password=xxxxxx"
102 <Directory /usr/www/myhost/private>
103 # mod_authn_core and mod_auth_basic configuration
108 # To cache credentials, put socache ahead of dbd here
109 AuthBasicProvider socache dbd
111 # Also required for caching: tell the cache to cache dbd lookups!
112 AuthnCacheProvideFor dbd
113 AuthnCacheContext my-server
115 # mod_authz_core configuration
118 # mod_authn_dbd SQL query to authenticate a user
119 AuthDBDUserPWQuery "SELECT password FROM authn WHERE user = %s"
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>
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_".
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.
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>
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"
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>.
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>
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.
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>
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"
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>.
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>
209 <div class="bottomlang">
210 <p><span>Available Languages: </span><a href="../en/mod/mod_authn_dbd.html" title="English"> en </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&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';
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';
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);
225 d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
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') {