URL: http://www.switch.ch/aai/docs/shibboleth/SWITCH/1.3/idp/install-cas.html
Author: Patrik Schnellmann - SWITCH
$Date: 2007/08/10 14:21:55 $
$Revision: 1.7 $

How To Install CAS for Shibboleth IdP

In the following the installation of the CAS (Central Authentication System) for a Shibboleth Service 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 http://www.ja-sig.org for more information.

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.

Install CAS-Server

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

Get the cas-server

$ wget http://www.ja-sig.org/downloads/cas/cas-server-2.0.12.tar.gz

Extract the package

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

Kerberos AuthHandler

First, get the following files:

  1. Copy KerberosAuthHandler.java and CASCallbackHandler.java to cas-server-2.0.12/src/edu/yale/its/tp/cas/auth/provider/
  2. 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/init.d/tomcat (or in /etc/default/tomcat, if available): 

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 modifications in other tomcat startup scripts.

Customize, build and install in Tomcat

  1. Customize login page and logos in directory cas-server-2.0.12/web/ (all the .jsp pages).
  2. Build cas.war. In the cas-server-2.0.12 directory, do: 
    $ ant dist
  3. Install cas-server web archive in Tomcat: 
    $ cp lib/cas.war /opt/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

The part for CAS Client is also described in the Shibboleth Identity Provider 1.3 Installation Guide on install-idp-1.3-debian.html. If the reader is following that guide, he is advised to skip this section and return back to the main installation guide.

Build CAS-Client

  1. Extract cas-client-java-2.1.1.tar.gz and build the cas-client Java archive: 
    $ tar -xzf cas-client-java-2.1.1.tar.gz
$ cd cas-client-java-2.1.1
$ ant jar
  2. Copy the casclient.jar to /opt/shibboleth-idp-install/webApplication/WEB-INF/lib/ (if to be included into a .war file) or directly to /opt/tomcat/webapps/shibboleth-idp/WEB-INF/lib.
  3. If needed, deploy the Shibboleth Idp web application again (call ant in /opt/shibboleth-idp-install/ and/or restart Tomcat.)

Configure Filters for the Shibboleth Idp Web App

In /opt/shibboleth-idp-install/webAppConfig/dist.idp.xml or /opt/tomcat/webapps/shibboleth-idp/WEB-INF/web.xml insert the following lines to add the CASFilter: 

<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://www.example.ch/cas/login</param-value>
      </init-param>
      <init-param>
         <param-name>edu.yale.its.tp.cas.client.filter.validateUrl</param-name>
         <param-value>https://www.example.ch/cas/proxyValidate</param-value>
      </init-param>
      <init-param>
         <param-name>edu.yale.its.tp.cas.client.filter.serverName</param-name>
         <param-value>www.example.ch</param-value>
      </init-param>
      <!-- expose REMOTE_USER (from CAS Client version 2.1.0) -->
      <init-param>
         <param-name>edu.yale.its.tp.cas.client.filter.wrapRequest</param-name>
         <param-value>true</param-value>
      </init-param>
   </filter>


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

   <!-- servlet configuration -->
   <!-- ... -->

</web-app>

Sample Configuration Files

krb5.conf

krb5.conf 

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

# DCx is the name of the active directory server(s) acting as
# the KDC(s) in your windows network
[realms]
        EXAMPLE.CH = {
                kdc = DC1.example.ch
		kdc = DC2.example.ch
        }

[domain_realm]
	.example.ch = EXAMPLE.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

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.7 2007/08/10 14:21:55 schnell Exp $