| <?xml version="1.0"?> |
| <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd"> |
| <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?> |
| <!-- $LastChangedRevision$ --> |
| |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| |
| <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> |
| <seealso><a href="../misc/password_encryptions.html">Password Formats</a></seealso> |
| |
| <section id="socache"> |
| <title>Performance and Cacheing</title> |
| <p>Some users of DBD authentication in HTTPD 2.2/2.4 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 <module>mod_authn_socache</module> |
| to cache credentials and take most of the load off the database.</p> |
| </section> |
| |
| <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> |
| <highlight language="config"> |
| # 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 |
| |
| <Directory "/usr/www/myhost/private"> |
| # 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" |
| </Directory> |
| </highlight> |
| </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> |
| <highlight language="config"> |
| AuthDBDUserPWQuery "SELECT password FROM authn WHERE user = %s" |
| </highlight> |
| <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> |
| <p>The encrypted password format depends on which authentication |
| frontend (e.g. <module>mod_auth_basic</module> or |
| <module>mod_auth_digest</module>) is being used. See <a |
| href="../misc/password_encryptions.html">Password Formats</a> for |
| more information.</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 in a |
| digest authentication process. |
| 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> |
| <highlight language="config"> |
| AuthDBDUserRealmQuery "SELECT password FROM authn WHERE user = %s AND realm = %s" |
| </highlight> |
| <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> |
| <p>The encrypted password format depends on which authentication |
| frontend (e.g. <module>mod_auth_basic</module> or |
| <module>mod_auth_digest</module>) is being used. See <a |
| href="../misc/password_encryptions.html">Password Formats</a> for |
| more information.</p> |
| </usage> |
| </directivesynopsis> |
| |
| </modulesynopsis> |