Apache mod_auth_cas Client

In this Section

Overview

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 mod_cas.

Installation

Note

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)
  1. Change directory to src:
    cd mod_auth_cas/src
  2. Build and install
    apxs -i -lssl -lcurl -c mod_auth_cas.c
  3. If need be (installation fails), the shared object file may be copied directly from .libs/mod_auth_cas.so to the Apache modules directory.
  4. The APXS utility may be named apxs2, depending on Linux distribution.
- Autoconf
```
cd mod_auth_cas
./configure
make
make install
```
  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.
CAS Configuration options
```
<IfModule mod_auth_cas.c>
CASLoginURL https://cas.ucdavis.edu/cas/login
CASValidateURL https://cas.ucdavis.edu/cas/serviceValidate
CASCertificatePath /etc/certs/cert.pem
CASCookiePath /tmp/cas/
CASSSOEnabled On
CASValidateServer On
CASDebug Off
</IfModule>
...
<Directory "/var/www/html/secure">
 <IfModule mod_auth_cas.c>
   AuthType CAS
   AuthName "UC Davis CAS"
 </IfModule>
   Require valid-user
</Directory>
```
- 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/pki/tls/certs/ca-bundle.crt or /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:
```
<html>
<head></head>
<body>
<p>Hi, I'm protected by CAS.</p>
<p>REMOTE_USER =

</p>
</body>
</html>
```
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 http://myserver.ucdavis.edu/secure/.

For HTTPS on ports 443 and 8443:
The server-level config is not inherited in the SSL-enabled virtual host.

<VirtualHost _default_:443>
ServerName myserver.ucdavis.edu
...
<IfModule mod_auth_cas.c>
...
</IfModule>
...
<Directory "/var/www/html/secure">
  DirectoryIndex index.shtml index.html
  AddHandler server-parsed .shtml
  Options +IncludesNoExec
  SSLOptions +StdEnvVars
  <IfModule mod_auth_cas.c>
    AuthType CAS
    AuthName "UC Davis"
    Require valid-user
  </IfModule>
</Directory>

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.

CentOS 5.x
OS X

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:

<Directory "/example/secure">
	AllowOverride All

	<IfModule mod_auth_cas.c>
	AuthType CAS
	AuthName "UC Davis CAS"
	</IfModule>

	AuthGroupFile /path/to/group/file

	Require group secureusers
	Satisfy All
</Directory>

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.

CASGateway /insecure

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.

Troubleshooting

I can authenticate to CAS, but don't get access to my site/application - Generally these issues boil down to one of two issues:
- Incorrect Validation URL - Ensure CASValidateURL is set to: https://cas.ucdavis.edu/cas/serviceValidate
- Certificate Validation Failure - When using the cas-test instance, you must have CASValidateServer set to Off.
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.

Files

	File	Modified
Labels No labels Preview View	File mod_auth_cas_trunk-46429.patch	Aug 21, 2009 by Brian Donnelly
Labels No labels Preview View	ZIP Archive mod_auth_cas.zip	Aug 21, 2009 by Brian Donnelly

Download All