mod_auth_db.html revision 1e895b30bf4833c928334fad80fac8be169ab877
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrews<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrews<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrews BGCOLOR="#FFFFFF"
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrews TEXT="#000000"
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrews LINK="#0000FF"
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrews VLINK="#000080"
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrews ALINK="#FF0000"
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrews<!--#include virtual="header.html" -->
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark AndrewsThis module is contained in the <code>mod_auth_db.c</code> file, and
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrewsis not compiled in by default. It provides for user authentication using
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark AndrewsBerkeley DB files. It is an alternative to <A HREF="mod_auth_dbm.html">DBM</A>
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrewsfiles for those systems which support DB and not DBM. It is only
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrewsavailable in Apache 1.1 and later.
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrews<li><A HREF="#authdbgroupfile">AuthDBGroupFile</A>
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrews<li><A HREF="#authdbuserfile">AuthDBUserFile</A>
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrews<li><A HREF="#authdbauthoritative">AuthDBAuthoritative</A>
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrews<A name="authdbgroupfile"><h2>AuthDBGroupFile</h2></A>
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrews<!--%plaintext <?INDEX {\tt AuthDBGroupFile} directive> -->
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrews<strong>Syntax:</strong> AuthDBGroupFile <em>filename</em><br>
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrews<Strong>Context:</strong> directory, .htaccess<br>
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark AndrewsThe AuthDBGroupFile directive sets the name of a DB file containing the list
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrewsof user groups for user authentication. <em>Filename</em> is the absolute path
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrewsto the group file.<p>
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark AndrewsThe group file is keyed on the username. The value for a user is a
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrewscomma-separated list of the groups to which the users belongs. There must
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrewsbe no whitespace within the value, and it must never contain any colons.<p>
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark AndrewsSecurity: make sure that the AuthDBGroupFile is stored outside the
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrewsdocument tree of the web-server; do <em>not</em> put it in the directory that
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrewsit protects. Otherwise, clients will be able to download the
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark AndrewsAuthDBGroupFile unless otherwise protected.<p>
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark AndrewsCombining Group and Password DB files: In some cases it is easier to
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrewsmanage a single database which contains both the password and group
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrewsdetails for each user. This simplifies any support programs that need
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrewsto be written: they now only have to deal with writing to and locking
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrewsa single DBM file. This can be accomplished by first setting the group
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrewsand password files to point to the same DB file:<p>
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark AndrewsThe key for the single DB record is the username. The value consists of <p>
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark AndrewsUnix Crypt-ed Password : List of Groups [ : (ignored) ]
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark AndrewsThe password section contains the Unix crypt() password as before. This is
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrewsfollowed by a colon and the comma separated list of groups. Other data may
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrewsoptionally be left in the DB file after another colon; it is ignored by the
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrewsauthentication module. <p>
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark AndrewsSee also <A HREF="core.html#authname">AuthName</A>,
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrews<A HREF="#authdbuserfile">AuthDBUserFile</A>.<p><hr>
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrews<A name="authdbuserfile"><h2>AuthDBUserFile</h2></A>
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrews<!--%plaintext <?INDEX {\tt AuthDBUserFile} directive> -->
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrews<strong>Syntax:</strong> AuthDBUserFile <em>filename</em><br>
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrews<Strong>Context:</strong> directory, .htaccess<br>
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark AndrewsThe AuthDBUserFile directive sets the name of a DB file containing the list
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrewsof users and passwords for user authentication. <em>Filename</em> is the
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrewsabsolute path to the user file.<p>
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark AndrewsThe user file is keyed on the username. The value for a user is the
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrewscrypt() encrypted password, optionally followed by a colon and
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrewsarbitrary data. The colon and the data following it will be ignored
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrewsby the server.<p>
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark AndrewsSecurity: make sure that the AuthDBUserFile is stored outside the
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrewsdocument tree of the web-server; do <em>not</em> put it in the directory that
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrewsit protects. Otherwise, clients will be able to download the
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark AndrewsAuthDBUserFile.<p>
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark AndrewsImportant compatibility note: The implementation of "dbmopen" in the
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrewsapache modules reads the string length of the hashed values from the
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark AndrewsDB data structures, rather than relying upon the string being
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark AndrewsNULL-appended. Some applications, such as the Netscape web server,
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrewsrely upon the string being NULL-appended, so if you are having trouble
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrewsusing DB files interchangeably between applications this may be a
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrewspart of the problem. <p>
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark AndrewsSee also <A HREF="core.html#authname">AuthName</A>,
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrews<A HREF="#authdbgroupfile">AuthDBGroupFile</A>.<p>
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrews<A name="authdbauthoritative"><h2>AuthDBAuthoritative</h2></A>
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrews<!--%plaintext <?INDEX {\tt AuthDBAuthoritative} directive> -->
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrews<strong>Syntax:</strong> AuthDBAuthoritative < <strong> on</strong>(default) | off > <br>
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrews<Strong>Context:</strong> directory, .htaccess<br>
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark AndrewsSetting the AuthDBAuthoritative directive explicitly to <b>'off'</b>
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrewsallows for both authentication and authorization to be passed on
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrewsto lower level modules (as defined in the <code>Configuration</code>
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrewsand <code>modules.c</code> file if there is <b>no userID</b> or
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrews<b>rule</b> matching the supplied userID. If there is a userID
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrewsand/or rule specified; the usual password and access checks will
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrewsbe applied and a failure will give an Authorization Required reply.
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark AndrewsSo if a userID appears in the database of more than one module; or
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrewsif a valid require directive applies to more than one module; then
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrewsthe first module will verify the credentials; and no access is
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrewspassed on; regardless of the AuthAuthoritative setting. <p>
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark AndrewsA common use for this is in conjunction with one of the basic auth
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrewsmodules; such as <a href="mod_auth.html"><code>mod_auth.c</code></a>.
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark AndrewsWhereas this DB module supplies the bulk of the user credential
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrewschecking; a few (administrator) related accesses fall through to
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrewsa lower level with a well protected .htpasswd file. <p>
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrews<b>Default:</b> By default; control is not passed on; and an unknown
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark AndrewsuserID or rule will result in an Authorization Required reply. Not
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrewssetting it thus keeps the system secure; and forces an NSCA compliant
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrewsbehaviour. <p>
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark AndrewsSecurity: Do consider the implications of allowing a user to allow
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrewsfall-through in his .htaccess file; and verify that this is really
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrewswhat you want; Generally it is easier to just secure a single
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrews.htpasswd file, than it is to secure a database which might have
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrewsmore access interfaces.
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark AndrewsSee also <A HREF="core.html#authname">AuthName</A>,
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrews<A HREF="#authdbgroupfile">AuthDBGroupFile</A>.<p>
c3c8823fed039b3a2b8e5ca8bc2f3301d1dd840eMark Andrews<!--#include virtual="footer.html" -->