mod_auth_db.html revision 65a1588701f9e5d0f62261d0da85733a23edc92f
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync<html xmlns="http://www.w3.org/1999/xhtml">
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync <head>
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync <meta name="generator" content="HTML Tidy, see www.w3.org" />
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync <title>Apache module mod_auth_db</title>
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync </head>
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync vlink="#000080" alink="#FF0000">
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync <!--#include virtual="header.html" -->
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync <h1 align="CENTER">Module mod_auth_db</h1>
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync <p>This module provides for user authentication using Berkeley
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync DB files.</p>
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync <p><a href="module-dict.html#Status"
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync rel="Help"><strong>Status:</strong></a> Extension<br />
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync <a href="module-dict.html#SourceFile"
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync rel="Help"><strong>Source File:</strong></a>
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync mod_auth_db.c<br />
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync <a href="module-dict.html#ModuleIdentifier"
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync rel="Help"><strong>Module Identifier:</strong></a>
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync auth_db_module</p>
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync <h2>Summary</h2>
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync <p>This module provides an alternative to <a
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync href="mod_auth_dbm.html">DBM</a> files for those systems which
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync support DB and not DBM. It is only available in Apache 1.1 and
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync later.</p>
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync <p>On some BSD systems (<em>e.g.</em>, FreeBSD and NetBSD) dbm
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync is automatically mapped to Berkeley DB. You can use either <a
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync href="mod_auth_dbm.html">mod_auth_dbm</a> or mod_auth_db. The
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync latter makes it more obvious that it's Berkeley DB. On other
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync platforms where you want to use the DB library you usually have
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync to install it first. See <a
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync href="http://www.sleepycat.com/">http://www.sleepycat.com/</a>
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync for the distribution. The interface this module uses is the one
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync from DB version 1.85 and 1.86, but DB version 2.x can also be
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync used when compatibility mode is enabled.</p>
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync <h2>Directives</h2>
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync <ul>
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync <li><a href="#authdbgroupfile">AuthDBGroupFile</a></li>
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync <li><a href="#authdbuserfile">AuthDBUserFile</a></li>
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync <li><a
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync href="#authdbauthoritative">AuthDBAuthoritative</a></li>
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync </ul>
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync <p>See also: <a href="core.html#satisfy">satisfy</a> and <a
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync href="core.html#require">require</a>.</p>
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync <hr />
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync <h2><a id="authdbgroupfile"
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync name="authdbgroupfile">AuthDBGroupFile directive</a></h2>
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync <!--%plaintext &lt;?INDEX {\tt AuthDBGroupFile} directive&gt; -->
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync <a href="directive-dict.html#Syntax"
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync rel="Help"><strong>Syntax:</strong></a> AuthDBGroupFile
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync <em>file-path</em><br />
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync <a href="directive-dict.html#Context"
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync rel="Help"><strong>Context:</strong></a> directory,
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync .htaccess<br />
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync <a href="directive-dict.html#Override"
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync rel="Help"><strong>Override:</strong></a> AuthConfig<br />
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync <a href="directive-dict.html#Status"
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync rel="Help"><strong>Status:</strong></a> Extension<br />
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync <a href="directive-dict.html#Module"
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync rel="Help"><strong>Module:</strong></a> mod_auth_db
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync <p>The AuthDBGroupFile directive sets the name of a DB file
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync containing the list of user groups for user authentication.
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync <em>File-path</em> is the absolute path to the group file.</p>
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync <p>The group file is keyed on the username. The value for a
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync user is a comma-separated list of the groups to which the users
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync belongs. There must be no whitespace within the value, and it
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync must never contain any colons.</p>
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync <p>Security: make sure that the AuthDBGroupFile is stored
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync outside the document tree of the web-server; do <em>not</em>
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync put it in the directory that it protects. Otherwise, clients
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync will be able to download the AuthDBGroupFile unless otherwise
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync protected.</p>
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync <p>Combining Group and Password DB files: In some cases it is
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync easier to manage a single database which contains both the
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync password and group details for each user. This simplifies any
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync support programs that need to be written: they now only have to
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync deal with writing to and locking a single DBM file. This can be
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync accomplished by first setting the group and password files to
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync point to the same DB file:</p>
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync <blockquote>
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync <code>AuthDBGroupFile /www/userbase<br />
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync AuthDBUserFile /www/userbase</code>
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync </blockquote>
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync The key for the single DB record is the username. The value
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync consists of
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync <blockquote>
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync <code>Unix Crypt-ed Password : List of Groups [ : (ignored)
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync ]</code>
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync </blockquote>
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync The password section contains the Unix crypt() password as
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync before. This is followed by a colon and the comma separated
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync list of groups. Other data may optionally be left in the DB
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync file after another colon; it is ignored by the authentication
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync module.
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync <p>See also <a href="core.html#authname">AuthName</a>, <a
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync href="core.html#authtype">AuthType</a> and <a
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync href="#authdbuserfile">AuthDBUserFile</a>.</p>
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync <hr />
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync <h2><a id="authdbuserfile"
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync name="authdbuserfile">AuthDBUserFile</a> directive</h2>
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync <!--%plaintext &lt;?INDEX {\tt AuthDBUserFile} directive&gt; -->
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync <a href="directive-dict.html#Syntax"
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync rel="Help"><strong>Syntax:</strong></a> AuthDBUserFile
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync <em>file-path</em><br />
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync <a href="directive-dict.html#Context"
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync rel="Help"><strong>Context:</strong></a> directory,
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync .htaccess<br />
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync <a href="directive-dict.html#Override"
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync rel="Help"><strong>Override:</strong></a> AuthConfig<br />
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync <a href="directive-dict.html#Status"
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync rel="Help"><strong>Status:</strong></a> Extension<br />
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync <a href="directive-dict.html#Module"
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync rel="Help"><strong>Module:</strong></a> mod_auth_db
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync <p>The AuthDBUserFile directive sets the name of a DB file
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync containing the list of users and passwords for user
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync authentication. <em>File-path</em> is the absolute path to the
38ae7e4efe803ea78b6499cd05a394db32623e41vboxsync user file.</p>
<p>The user file is keyed on the username. The value for a user
is the crypt() encrypted password, optionally followed by a
colon and arbitrary data. The colon and the data following it
will be ignored by the server.</p>
<p>Security: make sure that the AuthDBUserFile is stored
outside the document tree of the web-server; do <em>not</em>
put it in the directory that it protects. Otherwise, clients
will be able to download the AuthDBUserFile.</p>
<p>Important compatibility note: The implementation of
"dbmopen" in the apache modules reads the string length of the
hashed values from the DB data structures, rather than relying
upon the string being NULL-appended. Some applications, such as
the Netscape web server, rely upon the string being
NULL-appended, so if you are having trouble using DB files
interchangeably between applications this may be a part of the
problem.</p>
<p>A perl script called
href="/programs/dbmmanage.html"&gt;dbmmanage is included with
Apache. This program can be used to create and update DB format
password files for use with this module.</p>
See also <a href="core.html#authname">AuthName</a>, <a
href="core.html#authtype">AuthType</a> and <a
href="#authdbgroupfile">AuthDBGroupFile</a>.
<hr />
<h2><a id="authdbauthoritative"
name="authdbauthoritative">AuthDBAuthoritative</a>
directive</h2>
<!--%plaintext &lt;?INDEX {\tt AuthDBAuthoritative} directive&gt; -->
<a href="directive-dict.html#Syntax"
rel="Help"><strong>Syntax:</strong></a> AuthDBAuthoritative
on|off<br />
<a href="directive-dict.html#Default"
rel="Help"><strong>Default:</strong></a>
<code>AuthDBAuthoritative on</code><br />
<a href="directive-dict.html#Context"
rel="Help"><strong>Context:</strong></a> directory,
.htaccess<br />
<a href="directive-dict.html#Override"
rel="Help"><strong>Override:</strong></a> AuthConfig<br />
<a href="directive-dict.html#Status"
rel="Help"><strong>Status:</strong></a> Base<br />
<a href="directive-dict.html#Module"
rel="Help"><strong>Module:</strong></a> mod_auth
<p>Setting the AuthDBAuthoritative directive explicitly to
<strong>'off'</strong> allows for both authentication and
authorization to be passed on to lower level modules (as
defined in the <code>Configuration</code> and
<code>modules.c</code> file if there is <strong>no
userID</strong> or <strong>rule</strong> matching the supplied
userID. If there is a userID and/or rule specified; the usual
password and access checks will be applied and a failure will
give an Authorization Required reply.</p>
<p>So if a userID appears in the database of more than one
module; or if a valid <code>Require</code> directive applies to
more than one module; then the first module will verify the
credentials; and no access is passed on; regardless of the
AuthAuthoritative setting.</p>
<p>A common use for this is in conjunction with one of the
basic auth modules; such as <a
href="mod_auth.html"><code>mod_auth.c</code></a>. Whereas this
DB module supplies the bulk of the user credential checking; a
few (administrator) related accesses fall through to a lower
level with a well protected .htpasswd file.</p>
<p>By default, control is not passed on and an unknown userID
or rule will result in an Authorization Required reply. Not
setting it thus keeps the system secure and forces an NCSA
compliant behaviour.</p>
<p>Security: Do consider the implications of allowing a user to
allow fall-through in his .htaccess file; and verify that this
is really what you want; Generally it is easier to just secure
a single .htpasswd file, than it is to secure a database which
might have more access interfaces.</p>
<p>See also <a href="core.html#authname">AuthName</a>, <a
href="core.html#authtype">AuthType</a> and <a
href="#authdbgroupfile">AuthDBGroupFile</a>.</p>
<p><!--#include virtual="footer.html" -->
</p>
</body>
</html>