Apache Module mod_authn_dbd

Summary

This module provides authentication front-ends such asmod_auth_digest andmod_auth_basic to authenticate users by looking up users in SQL tables. Similar functionality is provided by, for example,mod_authn_file.

This module relies onmod_dbd to specify the backend database driver and connection parameters, and manage the database connections.

When usingmod_auth_basic ormod_auth_digest, this module is invoked via theAuthBasicProvider orAuthDigestProvider with thedbd value.

Topics

• Performance and Caching
• Configuration Example
• Exposing Login Information

Directives

• AuthDBDUserPWQuery
• AuthDBDUserRealmQuery

Bugfix checklist

• httpd changelog
• Known issues
• Report a bug

See also

• AuthName
• AuthType
• AuthBasicProvider
• AuthDigestProvider
• DBDriver
• DBDParams
• Password Formats
• Comments

Performance and Caching

Some users of DBD authentication in HTTPD 2.2/2.4 have reported that itimposes a problematic load on the database. This is most likely wherean 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 usemod_authn_socacheto cache credentials and take most of the load off the database.

Configuration Example

This simple example shows use of this module in the context ofthe Authentication and DBD frameworks.

# mod_dbd configuration# UPDATED to include authentication cachingDBDriver pgsqlDBDParams "dbname=apacheauth user=apache password=xxxxxx"DBDMin  4DBDKeep 8DBDMax  20DBDExptime 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>

Exposing Login Information

Whenever a query is made to the database server, allcolumn values in the first row returned by the query are placed in theenvironment, using environment variables with the prefix "AUTHENTICATE_".

If a database query for example returned the username, full nameand telephone number of a user, a CGI program will have access tothis information without the need to make a second independent databasequery to gather this additional information.

This has the potential to dramatically simplify the coding andconfiguration required in some web applications.

AuthDBDUserPWQueryDirective

TheAuthDBDUserPWQuery 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%s format specifier.

AuthDBDUserPWQuery "SELECT password FROM authn WHERE user = %s"

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 throughmod_authn_dbd.

Any additional column values in the first row returned by the query statement will be stored as environment variables with names of the formAUTHENTICATE_COLUMN.

The encrypted password format depends on which authentication frontend (e.g.mod_auth_basic ormod_auth_digest) is being used. SeePassword Formats for more information.

AuthDBDUserRealmQueryDirective

TheAuthDBDUserRealmQuery 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%s format specifiers.

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

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 throughmod_authn_dbd.

Any additional column values in the first row returned by the query statement will be stored as environment variables with names of the formAUTHENTICATE_COLUMN.

The encrypted password format depends on which authentication frontend (e.g.mod_auth_basic ormod_auth_digest) is being used. SeePassword Formats for more information.