URL: http://www.switch.ch/aai/docs/shibboleth/SWITCH/1.1/origin/install-cas.html
Author: Patrik Schnellmann
$Date: 2005/08/03 14:45:09 $
$Revision: 1.2 $

How To Install CAS for Shibboleth IdP

In the following the installation of the CAS (Central Authentication System) for a Shibboleth Identity Provider is described. CAS has been developed at the University of Yale. It is a Single Sign on System consisting of a server and a client part. The server part runs on Apache Tomcat, clients are available for Tomcat, as Apache modules and a lot more. See the CAS website for more information.

These installation instructions are applicable to Debian woody. With some variations they will do for other Linux distributions or Unixes where Tomcat runs.

Getting CAS

CAS can authenticate against every backend supported by Java such as LDAP, SQL databases, Kerberos, etc. For this purpose it uses so called Authentication Handlers are not part of the CAS distribution. To fill this gap, there is a Generic Authentication Handler for CAS in esup-cas package with Authentication Handlers for LDAP, SQL DBs. If you don't want to write your Authentication Handler on your own, rather use esup-cas than the original CAS package. However, esup-cas does not contain an AuthHandler for Kerberos, so the following guide will show you how to build the original CAS distribution with a custom Kerberos AuthHandler.

To get CAS, go to the CAS website with the Current CAS Stable Releases. Download the latest cas-server and cas-java-client packages.

To have Shibboleth work together with CAS, an additional filter, the "CASShibbolethUserPrincipalFilter", has to be installed. It is included in the remoteuserfilter.jar file.

Install CAS-Server

At the time of writing this document, the current stable version of cas-server was 2.0.12.

Extract the package

tar -xvzf cas-server-2.0.12.tar.gz

Kerberos AuthHandler

First, get the following files:

KerberosAuthHandler.java Authentication Handler for CAS
CASCallbackHandler.java CallbackHandler used within KerberosAuthHandler
krb5.conf Sample Kerberos configuration file
cas_jaas.conf Java Krb5LoginModule configuration

Copy KerberosAuthHandler.java and CASCallbackHandler.java to cas-server-2.0.12/src/edu/yale/its/tp/cas/auth/handler/

Configure CAS to use the KerberosAuthHandler in cas-server-2.0.12/web/WEB-INF/web.xml as follows:

<!-- Authentication handler -->
<context-param>
   <param-name>edu.yale.its.tp.cas.authHandler</param-name>
   <param-value>edu.yale.its.tp.cas.auth.provider.KerberosAuthHandler</param-value>
</context-param>

Copy the cas_jaas.conf and krb5.conf files to /etc/tomcat/. Configure Tomcat to use these configuration files. Add a line to set CATALINA_OPTS in /etc/default/tomcat:

CATALINA_OPTS="-Djava.security.auth.login.config=/etc/tomcat/cas_jaas.conf -Djava.security.krb5.conf=/etc/tomcat/krb5.conf"

Note: This is Debian specific. Other distributions require modifictions in other tomcat startup scripts.

Customize, build and install in Tomcat

Customize login page and logos in directory cas-server-2.0.12/web/ (all the .jsp pages).
Build cas.war. In the cas-server-2.0.12 directory, do:
```
ant dist
```
Install cas-server web archive in Tomcat:
```
cp lib/cas.war /usr/share/tomcat/webapps/
```
Tomcat should unpack the cas.war file and you should see a new directory cas in the webapps directory. This may require restarting Tomcat, depending on the configuration of its Deployer.

Configure Shibboleth Web App to use CAS

Build CAS-Client

Extract cas-client-java-2.1.1.tar.gz and build the cas-client Java archive:
```
tar -xvzf cas-client-java-2.1.1.tar.gz
cd cas-client-java-2.1.1
ant build
```
Copy the casclient.jar to shibboleth-origin-1.1/webApplication/WEB-INF/lib/ (if to be included into a .war file) or directly to shibboleth/WEB-INF/lib.
Copy remoteuserfilter.jar to the same directory as casclient.jar.

Configure Filters for shibboleth Web App

In shibboleth-origin-1.1/webAppConfig/origin.xml or shibboleth/WEB-INF/web.xml insert the following lines to add the CASFilter and CASShibbolethUserPrincipalFilter:

<web-app>

   <filter>
      <filter-name>CASFilter</filter-name>
      <filter-class>edu.yale.its.tp.cas.client.filter.CASFilter</filter-class>
      <init-param>
         <param-name>edu.yale.its.tp.cas.client.filter.loginUrl</param-name>
         <param-value>https://host.name.ch/cas/login</param-value>
      </init-param>
      <init-param>
         <param-name>edu.yale.its.tp.cas.client.filter.validateUrl</param-name>
         <param-value>https://host.name.ch/cas/proxyValidate</param-value>
      </init-param>
      <init-param>
         <param-name>edu.yale.its.tp.cas.client.filter.serverName</param-name>
         <param-value>host.name.ch</param-value>
      </init-param>
   </filter>

   <filter>
      <filter-name>CASShibbolethUserPrincipalFilter</filter-name>
      <filter-class>ch.SWITCH.aai.filters.CASShibbolethUserPrincipalFilter</filter-class>
   </filter>

   <filter-mapping>
      <filter-name>CASFilter</filter-name>
      <url-pattern>/HS/*</url-pattern>
   </filter-mapping>

   <filter-mapping>
      <filter-name>CASShibbolethUserPrincipalFilter</filter-name>
      <url-pattern>/HS/*</url-pattern>
   </filter-mapping>

   <!-- ... -->

</web-app>

Sample Configuration Files

krb5.conf

#
# krb5.conf
#
[libdefaults]
        default_realm = YOUR.DOMAIN.CH
	default_checksum = rsa-md5

# domainX.controller is the name of the active directory server(s) acting as
# the KDC(s) in your windows network
[realms]
        YOUR.DOMAIN.COM = {
                kdc = domain1.controller.ch
		kdc = domain2.controller.ch
        }

[domain_realm]
	.your.domain.ch = YOUR.DOMAIN.CH

[logging]
        default = CONSOLE
	kdc_rotate = {
# How often to rotate kdc.log. Logs will get rotated no more
# often than the period, and less often if the KDC is not used
# frequently.
		period = 1d

# how many versions of kdc.log to keep around (kdc.log.0, kdc.log.1, ...)
		versions = 10
	}

[appdefaults]
	kinit = {
		renewable = true
		forwardable = true
	}

cas_jaas.conf

/** 
 * Login Configuration for JAAS. 
 *
 * Specify that Kerberos v5 is a required login module for the 
 * example classes: GssExample and Mutual.
 */
edu.yale.its.tp.cas.auth.provider.KerberosAuthHandler {
  com.sun.security.auth.module.Krb5LoginModule 
	  required 
	  client=TRUE 
	  debug=FALSE 
	  useTicketCache=FALSE;
};

--   
$Id: install-cas.html,v 1.2 2005/08/03 14:45:09 schnell Exp $