mod_auth_dbm.html revision 1e895b30bf4833c928334fad80fac8be169ab877
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterland<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterland<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterland BGCOLOR="#FFFFFF"
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterland TEXT="#000000"
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterland LINK="#0000FF"
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterland VLINK="#000080"
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterland ALINK="#FF0000"
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterland<!--#include virtual="header.html" -->
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah WaterlandThis module is contained in the <code>mod_auth_dbm.c</code> file, and
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterlandis not compiled in by default. It provides for user authentication using
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterland<li><A HREF="#authdbmgroupfile">AuthDBMGroupFile</A>
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterland<li><A HREF="#authdbmuserfile">AuthDBMUserFile</A>
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterland<li><A HREF="#authdbmauthoritative">AuthDBMAuthoritative</A>
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterland<A name="authdbmgroupfile"><h2>AuthDbmGroupFile</h2></A>
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterland<!--%plaintext <?INDEX {\tt AuthDbmGroupFile} directive> -->
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterland<strong>Syntax:</strong> AuthDBMGroupFile <em>filename</em><br>
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterland<Strong>Context:</strong> directory, .htaccess<br>
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah WaterlandThe AuthDBMGroupFile directive sets the name of a DBM file containing the list
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterlandof user groups for user authentication. <em>Filename</em> is the absolute path
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterlandto the group file.<p>
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah WaterlandThe group file is keyed on the username. The value for a user is a
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterlandcomma-separated list of the groups to which the users belongs. There must
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterlandbe no whitespace within the value, and it must never contain any colons.<p>
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah WaterlandSecurity: make sure that the AuthDBMGroupFile is stored outside the
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterlanddocument tree of the web-server; do <em>not</em> put it in the directory that
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterlandit protects. Otherwise, clients will be able to download the
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah WaterlandAuthDBMGroupFile unless otherwise protected.<p>
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah WaterlandCombining Group and Password DBM files: In some cases it is easier to
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterlandmanage a single database which contains both the password and group
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterlanddetails for each user. This simplifies any support programs that need
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterlandto be written: they now only have to deal with writing to and locking
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterlanda single DBM file. This can be accomplished by first setting the group
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterlandand password files to point to the same DBM:<p>
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah WaterlandThe key for the single DBM is the username. The value consists of <p>
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah WaterlandUnix Crypt-ed Password : List of Groups [ : (ignored) ]
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah WaterlandThe password section contains the Unix crypt() password as before. This is
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterlandfollowed by a colon and the comma separated list of groups. Other data may
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterlandoptionally be left in the DBM file after another colon; it is ignored by the
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterlandauthentication module. This is what www.telescope.org uses for its combined
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterlandpassword and group database. <p>
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah WaterlandSee also <A HREF="core.html#authname">AuthName</A>,
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterland<A HREF="core.html#authtype">AuthType</A> and
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterland<A HREF="#authdbmuserfile">AuthDBMUserFile</A>.<p><hr>
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterland<A name="authdbmuserfile"><h2>AuthDBMUserFile</h2></A>
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterland<!--%plaintext <?INDEX {\tt AuthDBMUserFile} directive> -->
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterland<strong>Syntax:</strong> AuthDBMUserFile <em>filename</em><br>
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterland<Strong>Context:</strong> directory, .htaccess<br>
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah WaterlandThe AuthDBMUserFile directive sets the name of a DBM file containing the list
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterlandof users and passwords for user authentication. <em>Filename</em> is the
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterlandabsolute path to the user file.<p>
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah WaterlandThe user file is keyed on the username. The value for a user is the
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterlandcrypt() encrypted password, optionally followed by a colon and
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterlandarbitrary data. The colon and the data following it will be ignored
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterlandby the server.<p>
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah WaterlandSecurity: make sure that the AuthDBMUserFile is stored outside the
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterlanddocument tree of the web-server; do <em>not</em> put it in the directory that
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterlandit protects. Otherwise, clients will be able to download the
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah WaterlandAuthDBMUserFile.<p>
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah WaterlandImportant compatibility note: The implementation of "dbmopen" in the
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterlandapache modules reads the string length of the hashed values from the
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah WaterlandDBM data structures, rather than relying upon the string being
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah WaterlandNULL-appended. Some applications, such as the Netscape web server,
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterlandrely upon the string being NULL-appended, so if you are having trouble
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterlandusing DBM files interchangeably between applications this may be a
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterlandpart of the problem. <p>
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah WaterlandSee also <A HREF="core.html#authname">AuthName</A>,
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterland<A HREF="core.html#authtype">AuthType</A> and
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterland<A HREF="#authdbmgroupfile">AuthDBMGroupFile</A>.<p>
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterland<A name="authdbmauthoritative"><h2>AuthDBMAuthoritative</h2></A>
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterland<!--%plaintext <?INDEX {\tt AuthDBMAuthoritative} directive> -->
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterland<strong>Syntax:</strong> AuthDBMAuthoritative < <strong> on</strong>(default) | off > <br>
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterland<Strong>Context:</strong> directory, .htaccess<br>
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah WaterlandSetting the AuthDBMAuthoritative directive explicitly to <b>'off'</b>
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterlandallows for both authentication and authorization to be passed on
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterlandto lower level modules (as defined in the <code>Configuration</code>
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterlandand <code>modules.c</code> file if there is <b>no userID</b> or
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterland<b>rule</b> matching the supplied userID. If there is a userID
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterlandand/or rule specified; the usual password and access checks will
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterlandbe applied and a failure will give an Authorization Required reply.
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah WaterlandSo if a userID appears in the database of more than one module; or
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterlandif a valid require directive applies to more than one module; then
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterlandthe first module will verify the credentials; and no access is
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterlandpassed on; regardless of the AuthAuthoritative setting. <p>
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah WaterlandA common use for this is in conjunction with one of the basic auth
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterlandmodules; such as <a href="mod_auth.html"><code>mod_auth.c</code></a>.
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah WaterlandWhereas this DBM module supplies the bulk of the user credential
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterlandchecking; a few (administrator) related accesses fall through to
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterlanda lower level with a well protected .htpasswd file. <p>
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterland<b>Default:</b> By default; control is not passed on; and an unknown
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah WaterlanduserID or rule will result in an Authorization Required reply. Not
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterlandsetting it thus keeps the system secure; and forces an NSCA compliant
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterlandbehaviour. <p>
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah WaterlandSecurity: Do consider the implications of allowing a user to allow
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterlandfall-through in his .htaccess file; and verify that this is really
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterlandwhat you want; Generally it is easier to just secure a single
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterland.htpasswd file, than it is to secure a database which might have
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterlandmore access interfaces.
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah WaterlandSee also <A HREF="core.html#authname">AuthName</A>,
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterland<A HREF="core.html#authtype">AuthType</A> and
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterland<A HREF="#authdbmgroupfile">AuthDBMGroupFile</A>.<p>
5c51f1241dbbdf2656d0e10011981411ed0c9673Moriah Waterland<!--#include virtual="footer.html" -->