mod_auth_db.html revision 35f745d0d98970c673c5ef89cd48bbd2beeb2efe
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smith<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smith<!--#include virtual="header.html" -->
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn SmithThis module is contained in the <code>mod_auth_db.c</code> file, and
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smithis not compiled in by default. It provides for user authentication using
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn SmithBerkeley DB files. It is an alternative to <A HREF="mod_auth_dbm.html">DBM</A>
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smithfiles for those systems which support DB and not DBM. It is only
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smithavailable in Apache 1.1 and later.
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smith<li><A HREF="#authdbgroupfile">AuthDBGroupFile</A>
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smith<li><A HREF="#authdbauthoritative">AuthDBAuthoritative</A>
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smith<A name="authdbgroupfile"><h2>AuthDBGroupFile</h2></A>
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smith<!--%plaintext <?INDEX {\tt AuthDBGroupFile} directive> -->
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smith<strong>Syntax:</strong> AuthDBGroupFile <em>filename</em><br>
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smith<Strong>Context:</strong> directory, .htaccess<br>
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn SmithThe AuthDBGroupFile directive sets the name of a DB file containing the list
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smithof user groups for user authentication. <em>Filename</em> is the absolute path
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smithto the group file.<p>
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn SmithThe group file is keyed on the username. The value for a user is a
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smithcomma-separated list of the groups to which the users belongs. There must
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smithbe no whitespace within the value, and it must never contain any colons.<p>
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn SmithSecurity: make sure that the AuthDBGroupFile is stored outside the
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smithdocument tree of the web-server; do <em>not</em> put it in the directory that
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smithit protects. Otherwise, clients will be able to download the
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn SmithAuthDBGroupFile unless otherwise protected.<p>
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn SmithCombining Group and Password DB files: In some cases it is easier to
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smithmanage a single database which contains both the password and group
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smithdetails for each user. This simplifies any support programs that need
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smithto be written: they now only have to deal with writing to and locking
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smitha single DBM file. This can be accomplished by first setting the group
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smithand password files to point to the same DB file:<p>
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn SmithThe key for the single DB record is the username. The value consists of <p>
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn SmithUnix Crypt-ed Password : List of Groups [ : (ignored) ]
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn SmithThe password section contains the Unix crypt() password as before. This is
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smithfollowed by a colon and the comma separated list of groups. Other data may
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smithoptionally be left in the DB file after another colon; it is ignored by the
0b78b3f935d2de75ef952f2bafd0030aca9a077cMatthew Petroffauthentication module. <p>
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn SmithSee also <A HREF="core.html#authname">AuthName</A>,
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smith<A HREF="#authdbuserfile">AuthDBUserFile</A>.<p><hr>
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smith<A name="authdbuserfile"><h2>AuthDBUserFile</h2></A>
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smith<!--%plaintext <?INDEX {\tt AuthDBUserFile} directive> -->
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smith<strong>Syntax:</strong> AuthDBUserFile <em>filename</em><br>
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smith<Strong>Context:</strong> directory, .htaccess<br>
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn SmithThe AuthDBUserFile directive sets the name of a DB file containing the list
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smithof users and passwords for user authentication. <em>Filename</em> is the
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smithabsolute path to the user file.<p>
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn SmithThe user file is keyed on the username. The value for a user is the
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smithcrypt() encrypted password, optionally followed by a colon and
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smitharbitrary data. The colon and the data following it will be ignored
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smithby the server.<p>
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn SmithSecurity: make sure that the AuthDBUserFile is stored outside the
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smithdocument tree of the web-server; do <em>not</em> put it in the directory that
6b0fbf10b982696648debeede2b57f2b32a6a958Alex Valavanisit protects. Otherwise, clients will be able to download the
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn SmithAuthDBUserFile.<p>
0b78b3f935d2de75ef952f2bafd0030aca9a077cMatthew PetroffImportant compatibility note: The implementation of "dbmopen" in the
0b78b3f935d2de75ef952f2bafd0030aca9a077cMatthew Petroffapache modules reads the string length of the hashed values from the
0b78b3f935d2de75ef952f2bafd0030aca9a077cMatthew PetroffDB data structures, rather than relying upon the string being
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn SmithNULL-appended. Some applications, such as the Netscape web server,
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smithrely upon the string being NULL-appended, so if you are having trouble
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smithusing DB files interchangeably between applications this may be a
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smithpart of the problem. <p>
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn SmithSee also <A HREF="core.html#authname">AuthName</A>,
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smith<A HREF="#authdbgroupfile">AuthDBGroupFile</A>.<p>
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smith<A name="authdbauthoritative"><h2>AuthDBAuthoritative</h2></A>
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smith<!--%plaintext <?INDEX {\tt AuthDBAuthoritative} directive> -->
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smith<strong>Syntax:</strong> AuthDBAuthoritative < <strong> on</strong>(default) | off > <br>
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smith<Strong>Context:</strong> directory, .htaccess<br>
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn SmithSetting the AuthDBAuthoritative directive explicitly to <b>'off'</b>
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smithallows for both authentication and authorization to be passed on
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smithto lower level modules (as defined in the <code>Configuration</code>
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smithand <code>modules.c</code> file if there is <b>no userID</b> or
0b78b3f935d2de75ef952f2bafd0030aca9a077cMatthew Petroff<b>rule</b> matching the supplied userID. If there is a userID
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smithand/or rule specified; the usual password and access checks will
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smithbe applied and a failure will give an Authorization Required reply.
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn SmithSo if a userID appears in the database of more than one module; or
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smithif a valid require directive applies to more than one module; then
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smiththe first module will verify the credentials; and no access is
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smithpassed on; regardless of the AuthAuthoritative setting. <p>
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn SmithA common use for this is in conjunction with one of the basic auth
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smithmodules; such as <a href="mod_auth.html"><code>mod_auth.c</code></a>.
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn SmithWhereas this DB module supplies the bulk of the user credential
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smithchecking; a few (administrator) related accesses fall through to
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smitha lower level with a well protected .htpasswd file. <p>
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smith<b>Default:</b> By default; control is not passed on; and an unknown
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn SmithuserID or rule will result in an Authorization Required reply. Not
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smithsetting it thus keeps the system secure; and forces an NSCA compliant
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smithbehaviour. <p>
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn SmithSecurity: Do consider the implications of allowing a user to allow
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smithfall-through in his .htaccess file; and verify that this is really
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smithwhat you want; Generally it is easier to just secure a single
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smith.htpasswd file, than it is to secure a database which might have
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smithmore access interfaces.
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn SmithSee also <A HREF="core.html#authname">AuthName</A>,
2f5f997e354e7f4a02b6818bdc68fbece5cb237dJohn Smith<!--#include virtual="footer.html" -->