Installing the Apache authentication module under MacOS X

Ucam WebAuth

Ucam WebAuth v2.0 supports v3 of the protocol. This allows distinction between current users and all users. For more information please see this page https://wiki.cam.ac.uk/raven/Current_and_non-Current_users. It is recommended that mod_ucam_webauth v2.x is used for all new installs.

Installing & configuring Raven for 10.5 and later

For those users running 10.5+ on Intel hardware there is a prebuilt installer package to deploy the Raven module without the need for compilation etc. Users of previous versions of OS X should look at Legacy Raven info for 10.4 etc

Installing mod_ucam_webauth

1. Download the installer package from here and install. This will deploy mod_ucam_webauth built for 32 & 64 bit Intel hardware into /usr/libexec/apache2/
2. Download the necessary RSA public keys from https://raven.cam.ac.uk/project/keys/ and place them in into /etc/apache2/webauth_keys/. The easiest way to do this is to simply execute the following commands in Terminal:

sudo mkdir /etc/apache2/webauth_keys
cd /etc/apache2/webauth_keys
sudo curl -O https://raven.cam.ac.uk/project/keys/pubkey2

Editing Apache Configuration

It is recommended that you do not edit the primary httpd.conf file but configure apache through VirtualHost files. They are found in the following locations:

/etc/apache2/sites/ - 10.7 Lion and earlier inc Server versions

/Library/Server/Web/Config/apache2/sites/ - 10.8 Server only

It is highly recommended that you do not use Server Admin or Server to manage the web service post Raven configuration. These tools have a nasty habit of destroying configuration the GUI tools do not understand.

For a basic configuration add the following to the apache config file:

LoadModule ucam_webauth_module libexec/apache2/mod_ucam_webauth.so
AAKeyDir "/etc/apache2/webauth_keys"
AACookieKey "some random string"
<Directory "/path/to/protected/web/directory">
  AuthType Ucam-WebAuth
  Require valid-user
</Directory>

10.5, 10.6 & 10.7 specific edits

Add the following to the VirtualHosts file:

LoadModule authz_user_module libexec/apache2/mod_authz_user.so

10.8 Specific edits

Add the following to the VirtualHosts file:

LoadModule authz_user_module libexec/apache2/mod_authz_user.so

LoadModule authz_groupfile_module libexec/apache2/mod_authz_groupfile.so

Testing

Start/restart the web server and test. Check /var/log/apache2/error.log if you are having problems.

This is the minimum configuration required to restrict access to resources in a particular directory to users with a Ucam-WebAuth login. See https://raven.cam.ac.uk/project/apache/README.Config for further customisation options.

Building from Source

Should you wish to build the module from source then do the following:

1. Download and install Xcode AND the command line tools (sudo xcode-select --install is easiest) or install gcc & support files from another source
2. Download mod_ucam_webauth from https://raven.cam.ac.uk/project/apache/files/MacOS/ and expand the tar archive
3. cd into mod_ucam_webauth and type sudo apxs -c -i -lcrypto mod_ucam_webauth.c. This will build and install the Raven authentication module for the currently booted OS X system architecture.
4. Install the RSA keys and edit apache as described above.

If Xcode 4 or later users get the error "env: /Applications/Xcode.app/Contents/Developer/Toolchains/OSX10.8.xctoolchain/usr/bin/cc: No such file or directory" then paste in the following command as one line:

sudo ln -s /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain /Applications/Xcode.app/Contents/Developer/Toolchains/OSX10.8.xctoolchain

Replace OSX10.8.xctoolchain with OSX10.9.xctoolchain in the command above for Mavericks.

Apple forgot to include a symlink causing apxs to fail to find the compiler.

Legacy Raven info for 10.4 etc