Apache, Digest authentication

From Ubuntuwiki.net

Jump to: navigation, search



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 not be by default, as of Ubuntu 8.04LTS.) To enable it, you'll need to symlink auth_digest.load from /etc/apache2/mods-available to /etc/apache2/mods-enabled, and restart the server or force it to reload its configuration files.

me@box:~$ sudo ln -s /etc/apache2/mods-available/auth_digest.load /etc/apache2/mods-enabled/
me@box:~$ sudo /etc/init.d/apache2 force-reload
 * Reloading web server config apache2                                   [ OK ] 

Looks like everything started fine, right? Unfortunately, if you check your sites, you'll probably find that nothing loads... in which case you didn't have enough randomness in your system. Yes, really. Don't panic; just go here and come back after Apache's running properly again.


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
       AuthDigestDomain /
       AuthDigestProvider file
       AuthUserFile /data/www/sitename.tld/.htdigest

       Require valid-user

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

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 both the password AND the realm, so it won't work if you change the realm after it's created.

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:

me@box:~$ sudo /etc/init.d/apache2 force-reload
 * Reloading web server config apache2                                   [ OK ] 

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:

me@box:~$ ps waux | grep httpd
root     29344  0.0  0.6  27980 12368 ?        Ss   Jan14   0:01 /usr/sbin/apache2 -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.

me@box:~$ sudo du -hs /data
27G	/data
me@box:~$ ps waux | grep httpd
www-data  6966  0.1  0.9  33928 17076 ?        S    15:09   0:01 /usr/sbin/apache2 -k start
www-data  6967  0.1  0.9  33648 16760 ?        S    15:09   0:01 /usr/sbin/apache2 -k start
www-data  6968  0.1  0.9  33668 16720 ?        S    15:09   0:01 /usr/sbin/apache2 -k start
www-data  6972  0.1  0.9  33668 16784 ?        S    15:09   0:01 /usr/sbin/apache2 -k start
www-data  6976  0.2  0.9  33664 17320 ?        S    15:13   0:01 /usr/sbin/apache2 -k start
www-data  6977  0.1  0.9  33644 16652 ?        S    15:14   0:00 /usr/sbin/apache2 -k start
www-data  6978  0.0  0.9  34208 17336 ?        S    15:14   0:00 /usr/sbin/apache2 -k start
www-data  6982  0.1  0.9  34672 17576 ?        S    15:15   0:00 /usr/sbin/apache2 -k start
www-data  6983  0.1  0.9  33956 17580 ?        S    15:15   0:00 /usr/sbin/apache2 -k start
www-data  6989  0.1  0.9  33668 16656 ?        S    15:26   0:00 /usr/sbin/apache2 -k start
me        7008  0.0  0.0   2064   684 pts/1    R+   15:27   0:00 grep apache
root     29344  0.0  0.6  27980 12368 ?        Ss   Jan14   0:01 /usr/sbin/apache2 -k start

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.

Personal tools