What if you want to mix and match and have multiple types of authentication database within a single realm? How does Apache figure out which one to check first, and how does it know to consult another if the first one fails to find the credentials?

The answer has to do with authoritativeness. Each of the discretionary control modules includes a directive named something like AuthAuthoritative. Each module's version of this directive is named differently, so that it can be associated with that module and no other, so we also have AuthDBAuthoritative, AutDBMAuthoritative, and Anonymous_Authoritative.

If a module is considered authoritative, then when Apache gets a "I don't know this person" response, it won't look any further. If the module isn't authoritative, the server can proceed to consult another module.

Technical note: Actually, the decision isn't made by the server itself. Each module knows whether or not it's authoritative (based on the presence/absence/setting of its *Authoritative directive), and so in the case of a failure it signals the stop/continue answer to the server by returning either HTTP_UNAUTHORIZED or DECLINED respectively.

By default, the modules tend to consider themselves authoritative until you tell them otherwise, on the principle that it's better to be safe than sorry. You can make this explicit with a AuthAuthoritative On line, or allow responsibility sharing with AuthAuthoritative Off. (Use the appropriate directive for the module in question!)

The Htpasswd, Htdigest, and Dbmmanage Utilities
These three utilities are considered user tools, since you don't need to be the Webmaster in order to use them to create access control files for your own Web directory. As user applications, their documentation is in the man/man1 subdirectory of your Apache server installation; you can read it with a command such as:

   % man /usr/local/web/apache/man/man1/htpasswd.1

Given the assumptions stated earlier, you should find all three of these applications in the /usr/local/web/apache/bin/ directory, and the source of their man pages in /usr/local/web/apache/man/man1/.

The htpasswd application is used to create and maintain text-based authentication databases for use with the mod_auth module. It gets the username and options from the command line, prompts for and reads the password from standard input (twice, for verification), and stores the username and the encrypted password in the specified text file. When the Apache server receives credentials to verify, it encrypts the submitted password using the same algorithm as the stored password, and then compares the results--so the actual plaintext password doesn't live in a file on your system.

The syntax of the htpasswd command is:

    htpasswd [options] pwfile username [password]

The htpasswd command can encrypt the passwords using a variety of algorithms, indicated by the algorithm flag on the command line:

-m

Causes the password to be encrypted using an Apache-specific modified MD5 hash algorithm. Although no other application can understand passwords encrypted this way, they work on all Apache systems running 1.3.9 or later, and so you can transport your .htpasswd file from Linux to AIX to Solaris to Windows and have it work in each place without any changes. This is the default algorithm for the Windows and TPF platforms.

-d

Use the system's crypt() library routine to encrypt the password. This means that the encrypted passwords will be as safe as those in the system's user file--but they're probably not transportable to any other system.

-s

This will cause the password to be encrypted using the SHA algorithm, which is used by Netscape servers. This is useful when migrating from one server to the other.

The encryption algorithm used is particular to each entry in the file, so it's entirely possible for a file to contain passwords encrypted in different ways.

The htpasswd tool understands two other flags, which control other aspects than encryption:

-b

Get the password from the command line rather than reading it from stdin. This flag is primarily intended to help Windows Webmasters, but it's useful on other platforms as well, as it allows script-based password management in a non-interactive environment (such as allowing a user to change is password with a CGI script). However, since the password appears in plaintext on the command line, it might be visible to another user in the output of a ps command, and there's no verification that it was spelt correctly. Use this option with caution.

-c

By default, htpasswd assumes that the pwfile authentication database file already exists, and will update it. To create a new one, or completely overwrite an existing one, add the -c flag to the command line.

The htdigest and dbmmanage tools, also in the /usr/local/web/apache/bin/ directory, are similar to the htpasswd application. htdigest allows you to maintain text database files for use with Digest authentication, and dbmmanage supports the DB, DBM, GDBM, and NDBM database formats. dbmmanage is a Perl script, so you will need to have the Perl interpreter (version 5 or later) installed on your system in order to use it.

Location of Your Authentication Database
Remember that one of the main things the Apache Web server does is serve up files to visitors from the Internet--and don't put your authentication database files anyplace where that could happen to them!

For server-wide database files (that is, those managed by the Webmaster and listed in the httpd.conf file, rather than in users' .htaccess files), make sure you put them someplace where they're not under the DocumentRoot. Also make sure you don't put them someplace where they're under an Aliased or ScriptAliased directory.

For access control used by individual users to protect their own documents, the database files should not be under the directory listed in the UserDir directive in the server's httpd.conf file (typically public_html). Having your users put their database files in their home directory, or in another subdirectory (other than under public_html!) is a good idea.

Recent versions of Apache (those newer than 1.3.4 or so) include a default limitation on the common filenames used for per-directory authentication databases:

    <Files ~ "^\.ht">
        Order allow,deny
        Deny from all
    </Files>

This will prevent the server from processing requests for files named .htpasswd, .htaccess, .htpasswd-foo.db, and so on. Note that if you upgraded your Apache server from an earlier version, your httpd.conf file may not include these lines, and you may want to add them yourself.

Next: Conclusions/For More Information »