<?xml version="1.0"?>

<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">

<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>

<modulesynopsis metafile="mod_authn_dbd.xml.meta">

<name>mod_authn_dbd</name>

<description>User authentication using an SQL database</description>

<status>Extension</status>

<sourcefile>mod_authn_dbd.c</sourcefile>

<identifier>authn_dbd_module</identifier>

<compatibility>Available in Apache 2.1 and later</compatibility>

<summary>

<p>This module provides authentication front-ends such as

<module>mod_auth_digest</module> and <module>mod_auth_basic</module>

to authenticate users by looking up users in SQL tables.

Similar functionality is provided by, for example,

<module>mod_authn_file</module>.</p>

<p>This module relies on <module>mod_dbd</module> to specify

the backend database driver and connection parameters, and

manage the database connections.</p>

<p>When using <module>mod_auth_basic</module> or

<module>mod_auth_digest</module>, this module is invoked via the

<directive module="mod_auth_basic">AuthBasicProvider</directive> or

<directive module="mod_auth_digest">AuthDigestProvider</directive>

with the <code>dbd</code> value.</p>

</summary>

<seealso><directive module="mod_authn_core">AuthName</directive></seealso>

<seealso><directive module="mod_authn_core">AuthType</directive></seealso>

<seealso>

<directive module="mod_auth_basic">AuthBasicProvider</directive>

</seealso>

<seealso>

<directive module="mod_auth_digest">AuthDigestProvider</directive>

</seealso>

<seealso><directive module="mod_dbd">DBDriver</directive></seealso>

<seealso><directive module="mod_dbd">DBDParams</directive></seealso>

<section id="example">

<title>Configuration Example</title>

<p>This simple example shows use of this module in the context of

the Authentication and DBD frameworks.</p>

<example><pre>

# mod_dbd configuration

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"

AuthBasicProvider dbd

# 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></example>

</section>

<section id="exposed">

<title>Exposing Login Information</title>

<p>

If httpd was built against <glossary>APR</glossary> 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>

</section>

<directivesynopsis>

<name>AuthDBDUserPWQuery</name>

<description>SQL query to look up a password for a user</description>

<syntax>AuthDBDUserPWQuery <var>query</var></syntax>

<contextlist><context>directory</context>

</contextlist>

<usage>

<p>The <directive>AuthDBDUserPWQuery</directive> 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>

<example><title>Example</title><pre>

AuthDBDUserPWQuery \

"SELECT password FROM authn WHERE user = %s"

</pre></example>

<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 <module>mod_authn_dbd</module>.</p>

<p>If httpd was built against <glossary>APR</glossary> 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>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>AuthDBDUserRealmQuery</name>

<description>SQL query to look up a password hash for a user and realm.

</description>

<syntax>AuthDBDUserRealmQuery <var>query</var></syntax>

<contextlist><context>directory</context>

</contextlist>

<usage>

<p>The <directive>AuthDBDUserRealmQuery</directive> 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>

<example><title>Example</title><pre>

AuthDBDUserRealmQuery \

"SELECT password FROM authn WHERE user = %s AND realm = %s"

</pre></example>

<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 <module>mod_authn_dbd</module>.</p>

<p>If httpd was built against <glossary>APR</glossary> 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>

</usage>

</directivesynopsis>

</modulesynopsis>