View source for Installing the Apache authentication module under MacOS X

'''WARNING:''' Apple removed the OpenSSL library from MacOS 10.11 (El Capitan) onward. Since the Apache authentication module depends on OpenSSL for some of its function this means that the '''module can't easily be used with the supplied copy of Apache from 10.11 onward'''.

Options for anyone needing or currently using Raven authentication with Apache on MacOS include:
* Moving to Apache on a Linux platform
* Using Raven's Shibboleth service -- UIS have no experience of using this but the Shibboleth Consortium [https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPMacInstall appear to support running the Shibboleth SP under MacOS], and both [https://www.macports.org/ Macports] and [https://brew.sh/ Homebrew] include shibboleth-sp packages that may be usable with the MacOS version of Apache
* Install a separate copy of Apache and its dependencies either by hand or using [https://www.macports.org/ Macports] or [https://brew.sh/ Homebrew], and build a copy of the Apache Ucam WebAuth module against that using [http://raven.cam.ac.uk/project/apache/INSTALL the generic build instructions]

All of these options will be fiddly, and none will be GUI-based. Sorry.

==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.6 and later==

For those users running 10.6 and later there is a prebuilt installer package to deploy the Raven module without the need for compilation. Users of previous versions of OS X should look at [[Legacy Raven info for 10.4 etc]]

===Installing mod_ucam_webauth===

Choose the correct the installer package for your version of OS X. The module will be installed into /usr/libexec/apache/
*[http://raven.cam.ac.uk/project/apache/files/MacOS/mod_ucam_webauth_2.0.2_10.6-10.9.dmg 10.6 (Snow Leopard) to 10.9 (Mavericks)]
*[http://raven.cam.ac.uk/project/apache/files/MacOS/mod_ucam_webauth_2.0.2_10.10.dmg 10.10 (Yosemite)]
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:
 <tt>sudo mkdir /etc/apache2/webauth_keys
 cd /etc/apache2/webauth_keys
 sudo curl -O https://raven.cam.ac.uk/project/keys/pubkey2</tt>

===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:

<tt>/etc/apache2/sites/</tt> - all client version of OS X and 10.7 Server

<tt>/Library/Server/Web/Config/apache2/sites/</tt>  - 10.8 Server and later

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:

 <tt>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></tt>

====10.5, 10.6 & 10.7 specific edits====

Add the following to the VirtualHosts file:

<tt>LoadModule authz_user_module libexec/apache2/mod_authz_user.so</tt>

====10.8 or later specific edits====

Add the following to the VirtualHosts file:

<tt>LoadModule authz_user_module libexec/apache2/mod_authz_user.so

LoadModule authz_groupfile_module libexec/apache2/mod_authz_groupfile.so</tt>

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

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

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

Replace OSX10.8.xctoolchain with OSX10.9.xctoolchain etc as appropriate.

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

[[Legacy Raven info for 10.4 etc]]