mod_auth_cas was written to specifically target Apache 2.2 and the CAS v2 protocol, although it will also work with Apache 2.0 and the CAS v1 protocol. Much of the
mod_auth_cas design was based upon the original
These installation instructions are paraphrased from the
mod_auth_cas installation README. Please consult this file if you encounter difficulties.
- Obtain the package
Download from the Jasig Git repository (https://github.com/Jasig/mod_auth_cas).
git clone https://github.com/Jasig/mod_auth_cas.git
- Build the module
mod_auth_cas can be built two ways:
- APXS (preferred)
- Change directory to
- Build and install
apxs -i -lssl -lcurl -c mod_auth_cas.c
- If need be (installation fails), the shared object file may be copied directly from
.libs/mod_auth_cas.so to the Apache
- The APXS utility may be named
apxs2, depending on Linux distribution.
Note: configure can take an optional
--with-apxs=/path/to/apxs argument to specify the path to your APXS binary.
- Configure the Module
When using the autoconf installation method, your apache configruation should have been automatically changed to load the new cas module. Inspect your httpd.conf file looking for LoadModule auth_cas_module. If an entry exists, you can proceed to the next step. If not, follow these instructions:
- First, you must tell Apache to load the module. Find the location of the mod_auth_cas.so file and then add to your httpd.conf:
LoadModule auth_cas_module /path/to/mod_auth_cas.so
- Configure CAS Options
There are a number of CAS options that need to be configured at the server level.
AuthName "UC Davis CAS"
- Configuration Options Explained
- CASCertificatePath - Set this to the location of a certificate (authority) cache file for verifying the CAS server cert. Details are platform specific, but in Redhat Enterprise Linux, you should be able to use the default
cert.pem file. Please note that the location of this file matters:
- RHEL 5:
/etc/pki/tls/certs/ca-bundle.crt in the
openssl RPM package.
- RHEL 6:
/etc/ssl/certs/ca-bundle.crt in the
ca-certificates RPM package.
- CASCookiePath - Set this to a directory writable by the httpd service. It will be used to track authentication sessions.
- CASSSOEnabled - Setting this to on causes the mod_auth_cas module to respond to CAS Single Sign Out requests.
- CASSValidateServer - This setting causes
mod_auth_cas to validate the server certificate of the CAS server it contacts.
- CASSDebug - Turn on debugging when encountering problems with the module.
- Other Options - There are a number of other options that may be specified. Please refer to the documentation on the Aprero Jasig site for information about them.
- Test it out by creating a protected page.
Create /var/www/html/secure/index.shtml - this corresponds to file named in the <Directory> block of httpd.conf:
<p>Hi, I'm protected by CAS.</p>
- Restart the web server
When you've made these changes, restart your web server and access the page with your browser. It will probably be something like
- For HTTPS on ports 443 and 8443:
The server-level config is not inherited in the SSL-enabled virtual host.
DirectoryIndex index.shtml index.html
AddHandler server-parsed .shtml
AuthName "UC Davis"
Platform-Specific Instructions / Binaries
Building and deploying mod_auth_cas can require extra work on some platforms. The links below will refer you to information about various target platforms and the steps required to deploy mod_auth_cas to them. Where practical, we will also host binary versions of the modules.
Classlist / User File Configuration
Classlist and User File Authorization can be configured using the UCDavisAuthZ perl module. Installation instructions and the module download are available on the UCDavisAuthZ page. However, we now recommend the use of AuthGroupFile, a standard Apache extension.
To use AuthGroupFile with your CAS configuration, add the AuthGroupFile directive to your Location/Directory configuration:
AuthName "UC Davis CAS"
Require group secureusers
With that directive set, you will need to create a file at the configured location (/path/to/group/file) that has the following format:
secureusers: my_kerberos_login your_kerberos_login his_kerberos_login her_kerberos_login
Passthrough / Gateway Configuration
To enable Passthrough / Gateway, add a CASGateway directive to your CAS Directory Configuration. The value of the directive should be the relative path of a directory that will allow unauthenticated access. The argument MUST be a relative path.
IP Restriction Configuration
IP Restriction can be accomplished in two ways:
- We recommend use of the built-in mod_access Apache module. You can find further information about this at: http://httpd.apache.org/docs/1.3/mod/mod_access.html
- If necessary, the UCDavisAuthZ module contains the same IP Restriction feature as the Apache Distauth module. Installation instructions and the module download are available on the UCDavisAuthZ page.
- I can authenticate to CAS, but don't get access to my site/application - Generally these issues boil down to one of two issues:
- Single Sign Out Doesn't Work - The primary reasons for single-sign out failure are:
- SSO Support not enabled - Ensure you have CASSSOEnabled set to On in your apache mod_auth_cas configuration.
- Non SSL Urls - CAS will only send Single Sign Out messages to https urls. So, if the service you are protecting uses an http:// url instead of https:// it will not be able to participate in Single Sign Out.
- CAS Server Firewalled - The single sign out requests come from the CAS server, your server firewall must allow incoming https (port 443) requests.