mod_authn_dbm.xml revision f43ed9051a7f4db461d67ed4f7ece175b3dbca7c
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz<modulesynopsis>
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz<description>User authentication using DBM files</description>
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz<compatibility>Available in Apache 2.0.42 and later</compatibility>
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz <p>This module provides authentication front-ends such as
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz <module>mod_auth_digest</module> and <module>mod_auth_basic</module>
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz to authenticate users by looking up users in plain text password files.
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz Similar functionality is provided by <module>mod_authn_file</module>.</p>
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz <p>When using <module>mod_auth_basic</module> or
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz <module>mod_auth_digest</module>, this module is invoked via the
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz <directive module="mod_auth_basic">AuthBasicProvider</directive> or
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz <directive module="mod_auth_digest">AuthDigestProvider</directive>
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz with the 'dbm' value.</p>
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz<seealso><directive module="core">AuthName</directive></seealso>
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz<seealso><directive module="core">AuthType</directive></seealso>
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz <directive module="mod_auth_basic">AuthBasicProvider</directive>
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz <directive module="mod_auth_digest">AuthDigestProvider</directive>
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz<directivesynopsis>
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz<description>Sets the name of a database file containing the list of users and
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantzpasswords for authentication</description>
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz<syntax>AuthDBMUserFile <em>file-path</em></syntax>
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz<contextlist>
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz</contextlist>
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz <p>The <directive>AuthDBMUserFile</directive> directive sets the
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz name of a DBM file containing the list of users and passwords for
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz user authentication. <em>File-path</em> is the absolute path to
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz the user file.</p>
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz <p>The user file is keyed on the username. The value for a user is
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz the <code>crypt()</code> encrypted password, optionally followed
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz by a colon and arbitrary data. The colon and the data following it
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz will be ignored by the server.</p>
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz <p>Security: make sure that the
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz <directive>AuthDBMUserFile</directive> is stored outside the
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz document tree of the web-server; do <em>not</em> put it in the
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz directory that it protects. Otherwise, clients will be able to
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz download the <directive>AuthDBMUserFile</directive>.</p>
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz <p>Important compatibility note: The implementation of
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz "dbmopen" in the apache modules reads the string length of the
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz hashed values from the DBM data structures, rather than relying
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz upon the string being NULL-appended. Some applications, such as
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz the Netscape web server, rely upon the string being
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz NULL-appended, so if you are having trouble using DBM files
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz interchangeably between applications this may be a part of the
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz problem.</p>
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz <p>A perl script called
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz <a href="/programs/dbmmanage.html">dbmmanage</a> is included with
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz Apache. This program can be used to create and update DBM
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz format password files for use with this module.</p>
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz</directivesynopsis>
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz<directivesynopsis>
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz<description>Sets the type of database file that is used to
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantzstore passwords</description>
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz<syntax>AuthDBMType default|SDBM|GDBM|NDBM|DB</syntax>
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz<contextlist>
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz</contextlist>
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz<compatibility>Available in version 2.0.30 and later.</compatibility>
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz<p>Sets the type of database file that is used to store the passwords.
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantzThe default database type is determined at compile time. The
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantzavailability of other types of database files also depends on
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz<a href="/install.html#dbm">compile-time settings</a>.</p>
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz<p>It is crucial that whatever program you use to create your password
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantzfiles is configured to use the same type of database.</p>
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz</directivesynopsis>
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz<directivesynopsis>
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz<description>Sets whether authentication and authorization will be
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantzpasswed on to lower level modules</description>
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz<contextlist><context>directory</context><context>.htaccess</context>
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz</contextlist>
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz <p>Setting the <directive>AuthDBMAuthoritative</directive>
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz directive explicitly to <strong>'off'</strong> allows for both
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz authentication and authorization to be passed on to lower level
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz modules (as defined in the <code>Configuration</code> and
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz <code>modules.c</code> file if there is <strong>no userID</strong>
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz or <strong>rule</strong> matching the supplied userID. If there is
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz a userID and/or rule specified; the usual password and access
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz checks will be applied and a failure will give an Authorization
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz Required reply.</p>
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz <p>So if a userID appears in the database of more than one module;
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz or if a valid <directive module="core">Require</directive>
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz directive applies to more than one module; then the first module
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz will verify the credentials; and no access is passed on;
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz regardless of the <directive>AuthAuthoritative</directive> setting.</p>
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz <p>A common use for this is in conjunction with one of the
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz auth providers; such as <module>mod_authn_file</module>. Whereas this
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz DBM module supplies the bulk of the user credential checking; a
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz few (administrator) related accesses fall through to a lower
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz level with a well protected .htpasswd file.</p>
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz <p>By default, control is not passed on and an unknown userID
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz or rule will result in an Authorization Required reply. Not
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz setting it thus keeps the system secure and forces an NCSA
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz compliant behaviour.</p>
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz <p>Security: Do consider the implications of allowing a user to
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz allow fall-through in his .htaccess file; and verify that this
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz is really what you want; Generally it is easier to just secure
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz a single .htpasswd file, than it is to secure a database which
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz might have more access interfaces.</p>
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz</directivesynopsis>
f43ed9051a7f4db461d67ed4f7ece175b3dbca7cjerenkrantz</modulesynopsis>