Installing and configuring the mod_auth_cas module to work with Apache 2 on Ubuntu

This is to make use of the Central Authentication Service provided by IST for single-sign-on across campus.

NOTE: As of 2015-05, CAS has been deprecated in favour of ADFS

Using CAS, a web server only needs to supply a .htaccess containing require valid-user to populate Apache REMOTE_USER with the logged in user's WatIAM id. (see sample apache config at bottom of this page).

Note that for regular development, you don't necessarily need to install CAS. If your application uses "Basic Authentication" it will populate REMOTE_USER in the same way as CAS, so you can then drop it into a CAS environment and it should just work.

Fetch, build, and install the module

You need to install subversion to get the module source, and apache2-threaded-dev to build and install the module:

apt-get install subversion apache2-threaded-dev

Then, download, build, and install the source:

svn co https://www.ja-sig.org/svn/cas-clients/mod_auth_cas/trunk mod_auth_cas
cd mod_auth_cas/src
cp mod_auth_cas.h mod_auth_cas.h.orig
sed 's/^#undef APACHE2_0/#define APACHE2_0/g' mod_auth_cas.h.orig > mod_auth_cas.h
apxs2 -i -c mod_auth_cas.c

Set things up for the module to work

Get the CA certificate:

cd /etc/apache2/ssl
wget http://ist.uwaterloo.ca/security/IST-CA/certs/2.pem
mv 2.pem cacert.pem

Make a place for CAS to store cookies:

mkdir -m 700 /tmp/cas
chown www-data:www-data /tmp/cas

/tmp gets cleaned at reboot, so arrange the above happens at every boot.

NEW: Instructions to setup automatic creation of /tmp/cas at boot time:

I modified /etc/init.d/apache2 start up script for Ubuntu as follows:

Modify the "start" section as below:

        start)
                [ -f /etc/apache2/httpd.conf ] || touch /etc/apache2/httpd.conf
                [ -d /var/run/apache2 ] || mkdir -p /var/run/apache2                               
                [ -d /var/lock/apache2 ] || mkdir -p /var/lock/apache2
                chown www-data /var/lock/apache2
                #for the cas module - omar nafees added this
                [ -d /tmp/cas ] || mkdir -p /tmp/cas                                               
                chown www-data /tmp/cas                                                            
                chgrp www-data /tmp/cas                                                            
                #ssl_scache shouldn't be here if we're just starting up.                           
                [ -f /var/run/apache2/ssl_scache ] && rm -f /var/run/apache2/*ssl_scache*          
                log_begin_msg "Starting web server (apache2)..."                                   
                if $APACHE2CTL start; then                                                         
                        log_end_msg 0                                                              
                else                                                                               
                        log_end_msg 1                                                              
                fi                                                                                 
        ;;                                                         

Configure apache2 to load the module

Create /etc/apache2/mods-available/cas.load:

LoadModule auth_cas_module /usr/lib/apache2/modules/mod_auth_cas.so

Create /etc/apache2/mods-available/cas.conf:

  <IfModule mod_auth_cas.c>
      CASVersion 2
      CASDebug On
      CASCertificatePath /etc/apache2/ssl/cacert.pem
      CASLoginURL https://cas.uwaterloo.ca/cas/login
      CASValidateURL https://cas.uwaterloo.ca/cas/serviceValidate
  </IfModule>

Enable the module

sudo a2enmod cas

Example usage of the module

Protect your page(s) with the following in .htaccess (or apache config somewhere):

AuthType CAS
require user <list of userids>

Troubleshooting

If you get an error message such as this while rebooting apache2:

Cannot load /usr/lib/apache2/modules/mod_auth_ca
s.so into server: /usr/lib/apache2/modules/mod_auth_cas.so: undefined symbol:
ap_http_method
   ...fail!

... repeat the "build and install source step" above (by restoring the original header file by running rm mod_auth_cas.h; svn update in the mod_auth_cas directory) and do not execute the sed step just before running the apxs2 command above.

References

• https://strobe.uwaterloo.ca/~twiki/bin/view/ISTCSS/CASClientAuth
• https://strobe.uwaterloo.ca/~twiki/bin/view/ISTCSS/CasAuthServer