Apache, Digest Authentication

Revision as of 14:32, 5 June 2012

Overview

Traditionally, apache has used Basic authentication as a way to implement simple password protection on locations and directories. This is fine so far as it goes, but unfortunately while the .htpasswd file on the other end is encrypted, when a user authenticates the username and password are sent in cleartext. Apache also supports Digest authentication, which works almost identically, but does simple encryption of the transmitted username and password as well as the stored copies on the server.

Before you can use AuthDigest, you'll need to make sure the mod_auth_digest module is loaded in your Apache server. (It will be by default, if you have built Apache from ports.) The line enabling it in /usr/local/etc/apache22/httpd.conf looks like this:

LoadModule auth_digest_module libexec/apache22/mod_auth_digest.so

Directives

Once you've made sure your installation of Apache allows Digest authentication, you'll need to configure it for a Directory or a Location, which can be done in a .htaccess file in the directory to be protected (if AllowOverride Auth is set for that site), or in the Apache configs themselves. The configuration for Digest authentication looks very much like that for Basic authentication:

<Location />
    AuthName 'Private'

    AuthType Digest
    AuthDigestProvider file
    AuthDigestDomain /
    AuthUserFile /data/www/sitename.tld/.htdigest

    Require valid-user
</Location>

In this example, an entire website is protected with Digest authentication. Note the AuthDigestDomain directive; it should always be specified; otherwise the client will send the Authorization header for every request sent to the server. (In fact, in this example it wouldn't matter too much because the entire site WILL require the Authorization header - but it's a good habit to get into, particularly since you will usually only be protecting a certain part of a site.)

Also note that, unlike Basic authentication, the AuthName directive in a Digest-protected site serves as more than just "the text that pops up in a dialog box" when a user visits the protected area. With Digest authentication, the "Realm" specified by AuthName is a mandatory part of the user information in the .htdigest file. Presumably, this is so that you can use a single .htdigest file with multiple sites even if the sites have overlap in usernames. That's probably a bad idea in most cases, though.

Creating .htdigest Files

The other side of Digest authentication is creating the .htdigest file; for that you will use the htdigest command, which functions much like the htpasswd command. As mentioned above, however, you MUST specify a Realm when creating a user with htdigest, and the Realm MUST match the text in the AuthName directive. In this example, we'll create a .htdigest file to go along with the Digest directives shown above:

me@box:~$ htdigest -c /data/www/sitename.tld/.htdigest 'Private' 'username' 
Adding password for username in realm Private.
New password:
Re-type new password:
me@box:~$ 'cat /data/www/sitename.tld/.htdigest
username:Private:793b5dd9aceaa4314b3aa350b55d6bd3

As you can see, the .htdigest file contains the Realm as well as the username and a hashed copy of the password. Also note that we used single quotes to encapsulate username and realm in the htdigest command - that's not strictly necessary, but it's good practice; many sites want to use sentences rather than single words in the Authentication dialog box, which means you need to be able to use them in the htdigest command as well. And no, you can't just go into the .htdigest file and edit the Realm name afterwards - the hash is actually a hash of username:realm:password all together, so it won't work if you change the realm after it's created. (See http://httpd.apache.org/docs/2.2/misc/password_encryptions.html for details)

Now that you've got your .htdigest file created and your AuthDigest directives written, you'll need to restart Apache to put them in place (unless you used a .htaccess file to implement them instead of doing it in the Apache conf files).

Problems Restarting Apache

There's a nasty, unexpected SNAFU that you may run into the first time you restart Apache after enabling Digest authentication:

box# apachectl restart 
box#

It looks like everything restarted just fine... but when you go to browse any site on the server, you may get timeouts, and when you check to see if Apache's running, you may see only a single hung process doing nothing, instead of the usual 5 or 10 processes:

box# ps waux | grep httpd
root      2279    0.0  1.3 26904 13876  ??  Ss  2:44PM   0:08.13 /usr/local/sbin/httpd -k start

What's happening? Well, Digest authentication uses /dev/random pretty heavily, and you may not have enough randomness available on the system yet. If this is the case, then Apache will hang and do absolutely nothing until enough randomness accumulates for it to get the data it's looking for from the /dev/random device. (This may sound odd, but no, I am not kidding here.) If this happens to you, there's an easy workaround - generate some randomness by using the du command to thrash the heck out of your hard drives.

box# du -hs /data
39G /data
box# ps waux | grep httpd
www      15959  2.3  1.9 32528 19796  ??  S     2:51PM   0:00.47 /usr/local/sbin/httpd -k start
root      2279  0.0  1.3 26904 13876  ??  Ss    2:44PM   0:38.52 /usr/local/sbin/httpd -k start
www      15958  0.0  1.9 32532 19808  ??  I     2:51PM   0:00.47 /usr/local/sbin/httpd -k start
www      15960  0.0  1.3 26904 13892  ??  I     2:51PM   0:00.00 /usr/local/sbin/httpd -k start
www      15961  0.0  1.3 26904 13892  ??  I     2:51PM   0:00.00 /usr/local/sbin/httpd -k start
www      15962  0.0  1.3 26904 13892  ??  I     2:51PM   0:00.00 /usr/local/sbin/httpd -k start
www      15969  0.0  1.3 26904 13892  ??  I     2:52PM   0:00.00 /usr/local/sbin/httpd -k start
root     15983  0.0  0.0   348   212  p0  R+    2:53PM   0:00.00 grep http

There we go - now we see all of our Apache child processes running, and when we go back to check the sites on this server, we'll find that they're running just fine as well.