Building WebAuth on Leopard Server

| No Comments | No TrackBacks

I needed to get WebAuth working on my Leopard server, but out of the box, there are some issues with building the modules. I want it to work with the included Apache 2.2, so that I and other admins can use Apple's Server Admin tool to configure sites and directories. (Admittedly, I get that tingly, satisfying feeling when third-party tools fit like a puzzle piece in your operating system of choice. Can't discount that motivating incentive.)

But time pressures prevailed, so I had to prioritize a workaround to meet a looming deadline. Personally, "workarounds" almost always gives leave me dissatisfied, but in this case, it's a necessity. Here's how I implemented WebAuth, opting to give up the web server administration utility of Server Admin (which, at the end of the day, isn't too great a loss).

In short, you'll 1) build Apache 2.2 from source, 2) build WebAuth, 3) add the WebAuth Kerberos keytab, 4) add an SSL certificate, 5) hand-configure your conf files to protect your sites and 6) add a launchd file to start it all automatically.

Step 0:
I added this preliminary step as it might not be obvious. You'll need a few things first. Make sure you download and install Xcode 3. It's a free download after registering with Apple's Developer Connection. (Naturally, you'll need some command line skills and an administrator account, too.) You should also be listed as a user or administrator in Stanford's NetDB for your server, so you can make keytabs. All this said, these instructions are geared towards the Stanford community, though others might find them useful.

The first two steps are just building and installing. We'll get to configuring afterwards.

Step 1:
Download the latest Apache 2 source. At the time of this writing, it's version 2.2.8 and available from here: After expanding this archive, cd to the directory and begin the configure process. The Apache documentation is pretty clear. Though there are oodles of options, but the configuration I used is here:

./configure \
--enable-layout=Apache \
--with-ssl=/usr \
--with-mpm=prefork \
--disable-static \
--disable-unique-id \
--enable-shared \
--with-included-apr \
--enable-cgi \
--enable-cgid \
--enable-suexec \
--enable-so \
--enable-mods-shared="all deflate ssl dav cache logio proxy authn_alias mem_cache file_cache charset_lite dav_lock disk_cache"

The Apache layout option means that it will install at /usr/local/ —this is important, because your Leopard server already has two other Apache installations, and you'll probably not want to overwrite them. Additionally, since this is really the standard, default location for many Linux and Unix distributions, it's what WebAuth will expect, which will make life a little easier. The other configure options are worth reviewing on the Apache documentation webpage. You might be able to get away with less, and you might need more, but these are the flags that worked for me.

Presuming ./configure works for you, do a normal make then sudo make install. If everything goes right, you'll have /usr/local/apache2 with all the necessary components and modules.

Step 2:
Download the WebAuth source code. Visit the project page for this. At the time of this writing, 3.6.0 was the latest version. You should be able to do a straight-up ./configure with no flags, since it expects Apache directory to be /usr/local/apache2 (and Mac OS X 10.5 ain't going to tell it otherwise). My make and sudo make install came off without a hitch. This should dump the modules in the appropriate directory. (I've done this only on a few PowerPC Xserves, so you might need to flips some switches if you have an Intel-based Mac, especially if it's a Core 2 Duo or some other 64-bit processor.) Don't forget to do the make install-tests so we have something handy to test our setup.

Also, in the WebAuth instructions, you're instructed to make the /usr/local/apache2/conf/webauth directory readable and writable by the web daemon. On Mac OS X, that's usually www, which is not part of the wheel group. You have your choice on how to handle this, but I like using inheritable ACLs. You might consider something like this:

[root@myserver 22:24:47 /usr/local/apache2/conf]# chmod +ai "www allow read,write,add_file,add_subdirectory,delete_child" webauth

Step 3:
Since WebAuth is web-based Kerberos authentication, you'll need to make sure your server has a WA keytab, crafted for the University's MIT-style Kerberos realm ( You can now do this yourself using the wallet tool instead of first sending the campus Kerberos administrators and email request. You can build wallet yourself, at least, conceivably. I don't think that Mac OS X is one of the platforms on which it was developed, so getting wallet to build properly might be asking for another big project. Fortunately, you can use wallet on any of the Unix or Linux timeshare hosts. There are clear instructions on how to do this online.

Once you get the WebAuth keytab, you'll need to name the actual file to just "keytab" and put it in /usr/local/apache2/conf/webauth. Personally, I'm used to having Mac OS X keytabs always gathered together in /etc/krb5.keytab, and nothing will be broken if you have it there too—it just won't work unless it's in your conf directory, with that name. Here, you'll also want to apply your ACL.

[root@myserver 22:36:08 /usr/local/apache2/conf/webauth]# chmod +ai "www allow read,write" keytab

Step 4:
Now it's time to get your SSL cert and install that properly. WebAuth won't work without SSL, and you're more than welcome to use a self-signed certificate. That's fine if it's for a small group and you don't have restricted data on your server. The thing about self-signed certificates is that it can confuse and alarm users who face a distressing dialogue box about untrusted certificates when connecting with a web browser. On the upside, they're free.

But why not use a real, trusted, signed and free third-party certificate from an authority? There's a whole article on how to get a two-year SSL cert for your Stanford host. Check out this previous article here.

Step 5:
Now comes all the configuration tweaks. It's not much, and I'm sure you'd find it out yourself, but here are my notes which might help out.

Note the User and Group. They're "daemon" by default, and you'll need to change it to www for both. But in the default Apache httpd.conf file, they're nestled in tags for NT and Netware modules, which aren't active, so your changes won't take effect until you move "User www" and "Group www" out.

The typical location for web documents on unmodified systems is /Library/WebServer/Documents. Instead, your document root will be the more common /usr/local/apache2/htdocs. That doesn't mean you need to put your site there, of course. You can use symlinks to another location, or better, use a virtual site configuration with its own DocumentRoot and any additional <Directory> declarations on your filesystem.

Because you'll be running on an HFS filesystem, which has things like extended attributes, resource forks and case preservations (but not sensitivity), you need to beef up the exclusion list. These entries come from Apple's included httpd.conf.

<Files "rsrc">
    Order allow,deny
    Deny from all
    Satisfy All

<Files ~ "^\.([Hh][Tt]|[Dd][Ss]_[Ss])">
    Order allow,deny
    Deny from all
    Satisfy All

<DirectoryMatch ".*\.\.namedfork">
    Order allow,deny
    Deny from all
    Satisfy All

You will also need to make some modifications to the SSL section. On Mac OS X, SSL certificates managed by Server Admin normally get deposited in /etc/certificates. So it only made sense to include these paths when declaring where they exist in the mod_ssl block. And since I need to include my CA's intermediary certificate, I added that last line. I have a feeling I need to modify the SSLCipherSuite to something else, but I'm not certain. I'm sure Nessus will tell me.

<IfModule mod_ssl.c>
    SSLEngine On
    SSLCertificateFile "/etc/certificates/crc-resources.Stanford.EDU.crt"
    SSLCertificateKeyFile "/etc/certificates/crc-resources.Stanford.EDU.key"
    SSLCertificateChainFile "/etc/certificates/"
    SSLCertificateChainFile "/usr/local/apache2/conf/IPS-IPSCABUNDLE.crt"

Finally, about logs. Your custom-built Apache 2.2 will want to put logs into /usr/local/apache2/logs, but that's not a location that Mac OS X Server minds. So, in your configuration file somewhere, you might want to include these two lines. It will ensure that your logs will be rotated periodically. I took this from the Mac's included httpd.conf file, too, but made sure the output path was my custom Apache's log directory. (It would be great to modify the nightly scripts to compress and logroll these. I'll have to investigate that.) Here is manual page for the mod_log_config module options. The 5M is when the log reaches 5 MB, and the -420 is the offset to accommodate Pacific time. Note here that I'm using the rotatelogs command that comes with Mac OS X (you probably built one with Apache, too, in /usr/local/apache2/bin).

CustomLog '|/usr/sbin/rotatelogs "/usr/local/apache2/logs/access_log" 5M -420' "%h %l %u %t \"%r\" %>s %b"
ErrorLog '|/usr/sbin/rotatelogs "/usr/local/apache2/logs/error_log" 5M -420'

Step 6:
Now that you have Apache configured, you will want to have it launch automatically if the server gets restarted. I think there are a couple different ways to do this, but I chose to use a launchd item. I just copied /System/Library/LaunchDaemons/org.apache.httpd.plist to /Library/LaunchDaemons/ and edited it. You don't want to copy the launchd item and be done with it, because it needs its own identification string and path to your custom httpd. Here's mine, called org.apache.httpd-local.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "">
<plist version="1.0">

If you don't just reboot here, you need do something like:

launchctl load /Library/LaunchDaemons/org.apache.httpd-local.plist
launchctl start org.apache.http-local

There are still lots of other tweaks and modifications, depending on your purposes. Certainly read the Apache 2.2 manual, the WebAuth documentation and copy over parts from Apple's included configuration files.

Step 6.5
Oh, you'll probably also want to use the apachectl program to do graceful restarts and to test parameters, but the one that comes with Mac OS X is for the included Apache 2.2 in /usr/sbin. You'll want to use the one that's in /usr/local/apache2/bin. So I renamed that one to apachectl-apple symlinked the /usr/local/apache2/bin/apachectl to /usr/sbin. Make sure you leave the apachectl-1.3 alone, as that's the controller for the include Apache 1.3 that's also included with Mac OS X and is optional.

Good luck! I'm sure this isn't complete, full of grammatical and spelling errors and the like, but if it helps you, then rock on. If it doesn't, post a comment.

No TrackBacks

TrackBack URL:

Leave a comment

About this Entry

This page contains a single entry by Noah Abrahamson published on April 8, 2008 11:03 PM.

A simple bash script to email some log reports was the previous entry in this blog.

extended attributes on directories: invalid characters is the next entry in this blog.

Find recent content on the main index or look in the archives to find all content.