mod_authn_dbd.html.en revision 33cc86a567a0a9967470f5cdba8c856d2e1ce3b7
252N/A<?xml version="1.0" encoding="ISO-8859-1"?>
252N/A<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
252N/A<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
252N/A XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
252N/A This file is generated from xml source: DO NOT EDIT
252N/A XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
252N/A -->
252N/A<title>mod_authn_dbd - Apache HTTP Server</title>
252N/A<link href="/style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
252N/A<link href="/style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
252N/A<link href="/style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
252N/A<link href="/images/favicon.ico" rel="shortcut icon" /></head>
252N/A<body>
252N/A<div id="page-header">
252N/A<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.html">Directives</a> | <a href="/faq/">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p>
252N/A<p class="apache">Apache HTTP Server Version 2.3</p>
252N/A<img alt="" src="/images/feather.gif" /></div>
252N/A<div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="/images/left.gif" /></a></div>
252N/A<div id="path">
252N/A<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.3</a> &gt; <a href="./">Modules</a></div>
252N/A<div id="page-content">
252N/A<div id="preamble"><h1>Apache Module mod_authn_dbd</h1>
252N/A<div class="toplang">
252N/A<p><span>Available Languages: </span><a href="/en/mod/mod_authn_dbd.html" title="English">&nbsp;en&nbsp;</a></p>
252N/A</div>
252N/A<table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>User authentication using an SQL database</td></tr>
252N/A<tr><th><a href="module-dict.html#Status">Status:</a></th><td>Extension</td></tr>
252N/A<tr><th><a href="module-dict.html#ModuleIdentifier">Module�Identifier:</a></th><td>authn_dbd_module</td></tr>
252N/A<tr><th><a href="module-dict.html#SourceFile">Source�File:</a></th><td>mod_authn_dbd.c</td></tr>
252N/A<tr><th><a href="module-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.1 and later</td></tr></table>
252N/A<h3>Summary</h3>
252N/A
252N/A <p>This module provides authentication front-ends such as
252N/A <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>
to authenticate users by looking up users in SQL tables.
Similar functionality is provided by, for example,
<code class="module"><a href="/mod/mod_authn_file.html">mod_authn_file</a></code>.</p>
<p>This module relies on <code class="module"><a href="/mod/mod_dbd.html">mod_dbd</a></code> to specify
the backend database driver and connection parameters, and
manage the database connections.</p>
<p>When using <code class="module"><a href="/mod/mod_auth_basic.html">mod_auth_basic</a></code> or
<code class="module"><a href="/mod/mod_auth_digest.html">mod_auth_digest</a></code>, this module is invoked via the
<code class="directive"><a href="/mod/mod_auth_basic.html#authbasicprovider">AuthBasicProvider</a></code> or
<code class="directive"><a href="/mod/mod_auth_digest.html#authdigestprovider">AuthDigestProvider</a></code>
with the <code>dbd</code> value.</p>
</div>
<div id="quickview"><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="/images/down.gif" /> <a href="#authdbduserpwquery">AuthDBDUserPWQuery</a></li>
<li><img alt="" src="/images/down.gif" /> <a href="#authdbduserrealmquery">AuthDBDUserRealmQuery</a></li>
</ul>
<h3>Topics</h3>
<ul id="topics">
<li><img alt="" src="/images/down.gif" /> <a href="#socache">Performance and Cacheing</a></li>
<li><img alt="" src="/images/down.gif" /> <a href="#example">Configuration Example</a></li>
<li><img alt="" src="/images/down.gif" /> <a href="#exposed">Exposing Login Information</a></li>
</ul><h3>See also</h3>
<ul class="seealso">
<li><code class="directive"><a href="/mod/mod_authn_core.html#authname">AuthName</a></code></li>
<li><code class="directive"><a href="/mod/mod_authn_core.html#authtype">AuthType</a></code></li>
<li>
<code class="directive"><a href="/mod/mod_auth_basic.html#authbasicprovider">AuthBasicProvider</a></code>
</li>
<li>
<code class="directive"><a href="/mod/mod_auth_digest.html#authdigestprovider">AuthDigestProvider</a></code>
</li>
<li><code class="directive"><a href="/mod/mod_dbd.html#dbdriver">DBDriver</a></code></li>
<li><code class="directive"><a href="/mod/mod_dbd.html#dbdparams">DBDParams</a></code></li>
<li><a href="/misc/password_encryptions.html">Password Formats</a></li>
</ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
<div class="section">
<h2><a name="socache" id="socache">Performance and Cacheing</a></h2>
<p>Some users of DBD authentication in HTTPD 2.2 have reported that it
imposes a problematic load on the database. This is most likely where
an HTML page contains hundreds of objects (e.g. images, scripts, etc)
each of which requires authentication. Users affected (or concerned)
by this kind of problem should use <code class="module"><a href="/mod/mod_authn_socache.html">mod_authn_socache</a></code>
to cache credentials and take most of the load off the database.</p>
</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
<div class="section">
<h2><a name="example" id="example">Configuration Example</a></h2>
<p>This simple example shows use of this module in the context of
the Authentication and DBD frameworks.</p>
<div class="example"><pre>
# mod_dbd configuration
# UPDATED to include authentication cacheing
DBDriver pgsql
DBDParams "dbname=apacheauth user=apache password=xxxxxx"
DBDMin 4
DBDKeep 8
DBDMax 20
DBDExptime 300
&lt;Directory /usr/www/myhost/private&gt;
# mod_authn_core and mod_auth_basic configuration
# for mod_authn_dbd
AuthType Basic
AuthName "My Server"
# To cache credentials, put socache ahead of dbd here
AuthBasicProvider socache dbd
# Also required for caching: tell the cache to cache dbd lookups!
AuthnCacheProvideFor dbd
AuthnCacheContext my-server
# mod_authz_core configuration
Require valid-user
# mod_authn_dbd SQL query to authenticate a user
AuthDBDUserPWQuery \
"SELECT password FROM authn WHERE user = %s"
&lt;/Directory&gt;
</pre></div>
</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
<div class="section">
<h2><a name="exposed" id="exposed">Exposing Login Information</a></h2>
<p>
If httpd was built against <a class="glossarylink" href="/glossary.html#apr" title="see glossary">APR</a> version 1.3.0
or higher, then whenever a query is made to the database server, all
column values in the first row returned by the query are placed in the
environment, using environment variables with the prefix "AUTHENTICATE_".
</p>
<p>If a database query for example returned the username, full name
and telephone number of a user, a CGI program will have access to
this information without the need to make a second independent database
query to gather this additional information.</p>
<p>This has the potential to dramatically simplify the coding and
configuration required in some web applications.
</p>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="AuthDBDUserPWQuery" id="AuthDBDUserPWQuery">AuthDBDUserPWQuery</a> <a name="authdbduserpwquery" id="authdbduserpwquery">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>SQL query to look up a password for a user</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthDBDUserPWQuery <var>query</var></code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authn_dbd</td></tr>
</table>
<p>The <code class="directive">AuthDBDUserPWQuery</code> specifies an
SQL query to look up a password for a specified user. The user's ID
will be passed as a single string parameter when the SQL query is
executed. It may be referenced within the query statement using
a <code>%s</code> format specifier.</p>
<div class="example"><h3>Example</h3><pre>
AuthDBDUserPWQuery \
"SELECT password FROM authn WHERE user = %s"
</pre></div>
<p>The first column value of the first row returned by the query
statement should be a string containing the encrypted password.
Subsequent rows will be ignored. If no rows are returned, the user
will not be authenticated through <code class="module"><a href="/mod/mod_authn_dbd.html">mod_authn_dbd</a></code>.</p>
<p>If httpd was built against <a class="glossarylink" href="/glossary.html#apr" title="see glossary">APR</a> version 1.3.0
or higher, any additional column values in the first row returned by
the query statement will be stored as environment variables with
names of the form <code>AUTHENTICATE_<var>COLUMN</var></code>.
</p>
<p>The encrypted password format depends on which authentication
frontend (e.g. <code class="module"><a href="/mod/mod_authn_basic.html">mod_authn_basic</a></code> or
<code class="module"><a href="/mod/mod_authn_digest.html">mod_authn_digest</a></code>) is being used. See <a href="/misc/password_encryptions.html">Password Formats</a> for
more information.</p>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="AuthDBDUserRealmQuery" id="AuthDBDUserRealmQuery">AuthDBDUserRealmQuery</a> <a name="authdbduserrealmquery" id="authdbduserrealmquery">Directive</a></h2>
<table class="directive">
<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.
</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthDBDUserRealmQuery <var>query</var></code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authn_dbd</td></tr>
</table>
<p>The <code class="directive">AuthDBDUserRealmQuery</code> specifies an
SQL query to look up a password for a specified user and realm.
The user's ID and the realm, in that order, will be passed as string
parameters when the SQL query is executed. They may be referenced
within the query statement using <code>%s</code> format specifiers.</p>
<div class="example"><h3>Example</h3><pre>
AuthDBDUserRealmQuery \
"SELECT password FROM authn WHERE user = %s AND realm = %s"
</pre></div>
<p>The first column value of the first row returned by the query
statement should be a string containing the encrypted password.
Subsequent rows will be ignored. If no rows are returned, the user
will not be authenticated through <code class="module"><a href="/mod/mod_authn_dbd.html">mod_authn_dbd</a></code>.</p>
<p>If httpd was built against <a class="glossarylink" href="/glossary.html#apr" title="see glossary">APR</a> version 1.3.0
or higher, any additional column values in the first row returned by
the query statement will be stored as environment variables with
names of the form <code>AUTHENTICATE_<var>COLUMN</var></code>.
</p>
<p>The encrypted password format depends on which authentication
frontend (e.g. <code class="module"><a href="/mod/mod_authn_basic.html">mod_authn_basic</a></code> or
<code class="module"><a href="/mod/mod_authn_digest.html">mod_authn_digest</a></code>) is being used. See <a href="/misc/password_encryptions.html">Password Formats</a> for
more information.</p>
</div>
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="/en/mod/mod_authn_dbd.html" title="English">&nbsp;en&nbsp;</a></p>
</div><div id="footer">
<p class="apache">Copyright 2011 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>
<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.html">Directives</a> | <a href="/faq/">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p></div>
</body></html>