Central Authentication Service (CAS) is a single-sign-on system for web applications written in Java that we have begun to deploy here at Middlebury College. Web applications communicate with it by forwarding users to the central login page and then checking the responces via a web-service protocol.

A few months ago Ian and I got CAS installed on campus and began updating applications to work with it rather than maintaining their own internal connections to the Active Directory server. Throughout this process we ran into a few challenges (such as returning attributes with the authentication-success response) and a bug in CAS, but we worked through these and got CAS up and running successfully.

We are now at a point where we need to do some customizations to our CAS installation to deal with changes to the group structure in the Active Directory. As well, the bug I reported was apparently fixed in a new CAS version, an improvement I need to test before we update our production installation. Both of these require a bit more poking at CAS than we can do safely in our production environment, so I am now embarking on the process of setting up a Java/Tomcat development environment on my PC. I’m documenting this process here both for my own benefit (when I have to set this up again on my laptop) and in case it helps anyone else.

Read on for my step-by-step instructions for setting up a CAS development environment on OS X.

Since I’ve recently been successful using MacPorts to install Git (a source-code-management too), I decided to use MacPorts to install Apache Tomcat, Maven, and the other required software.

Part One: Get a default CAS installation up and running

Install the Apache Tomcat server using MacPorts

sudo port install tomcat5

A number of packages will not be successfully found by ports, resulting in the following error:

--->  Verifying checksum(s) for servlet24-api
Error: Checksum (md5) mismatch for apache-tomcat-5.5.25-src.tar.gz
Error: Target org.macports.checksum returned: Unable to verify file checksums

The easiest fix I found was do go to the apache website and directly download the file. Googling will find it. Once you’ve downloaded the file, find the corrupted one on your file-system with

find /opt/local/var/macports -name "apache-tomcat-5.5.25-src.tar.gz"

And replace the corrupted version with the directly downloaded one and then re-try installation with MacPorts:

sudo mv /Users/afranco/Downloads/apache-tomcat-5.5.25-src.tar.gz /opt/local/var/macports/distfiles/servlet24-api/

You will have to do this process several times for different packages that fail to download.

You will likely also need to install the mysql-connector-java. Download the zip archive and copy the .jar file inside to /Library/Java/Extensions/

Install Maven

Same thing as with Tomcat, try installing with ports and replace failed downloads.

sudo port install maven2

Also, make sure that /opt/loca/bin/ is to the front of the search path in your ~/.bash_profile. If not, the built-in mvn command may take precedence.

mvn -v
Apache Maven 2.1.0

Download CAS

I cloned the repository using Git so that I can easily maintain my private branches, but you can download it directly or checkout with subversion.

git svn clone  https://source.jasig.org/cas3 --trunk=trunk --branches=branches --tags=tags

Build CAS

Building CAS is accomplished by cd’ing to the directory in which you downloaded CAS and runing:

mvn package install

Because some of the tests rely on network particulars, I can’t get the build to work unless I skip tests by instead using:

mvn -Dmaven.test.skip=true package install

Install CAS

Copy the CAS war and files to the Tomcat webapps directory:

sudo cp -R cas-server-webapp/target/cas-server-webapp-3.x.x  /opt/local/share/java/tomcat5/webapps/cas
sudo cp -R cas-server-webapp/target/cas.war  /opt/local/share/java/tomcat5/webapps/cas.war

Start Tomcat/CAS

Start Tomcat:

sudo tomcatctl start

Point your browser at http://localhost:8080/cas/ and you should see the CAS login page.

Part Two: Customizing CAS

Create the customization overlay

Following the instructions for maintaining local customizations on the CAS wiki, I created a cas-server-midd subdirectory in my CAS-source directory and added a pom.xml file based on the example. Running maven properly generates a war file:

cd cas3/cas-server-midd/

mvn -Dmaven.test.skip=true package install

ls target/
	cas
	cas-server-midd-3.3.3-SNAPSHOT
	cas-server-webapp-3.3.3-SNAPSHOT
	cas.war
	maven-archiver
	pom-transformed.xml
	war

sudo rm -R  /opt/local/share/java/tomcat5/webapps/cas

sudo cp -R target/cas  /opt/local/share/java/tomcat5/webapps/cas

sudo cp target/cas.war  /opt/local/share/java/tomcat5/webapps/cas.war

sudo tomcatctl restart

Note that there is a target/cas/ directory in addition to target/cas-server-midd-3.x.x and target/cas-server-webapp-3.x.x directories. In this case, the target/cas/ one is the one we want to copy to the tomcat5/webapps directory. Refreshing your browser should still show the login page an not an error.

Adding Customizations

With the overlay directory structure in place, any files you add to the overlay directory (in my case cas3/cas-server-midd/src/...) will be used instead of the versions in cas3/cas-server-webapp/src/...

Using the overlay has the same result as editing the files in cas3/cas-server-webapp/src/..., but keeps the changes in their own directory structure and allows the overlay to only contain files with modifications. All other files have their defaults used.

Build and Install the customizations

Run the maven build process again and copy the result from our overlay target to the Tomcat directory:

cd cas3/cas-server-midd/
mvn -Dmaven.test.skip=true package install
sudo rm -R  /opt/local/share/java/tomcat5/webapps/cas
sudo cp -R target/cas  /opt/local/share/java/tomcat5/webapps/cas
sudo cp target/cas.war  /opt/local/share/java/tomcat5/webapps/cas.war
sudo tomcatctl restart

As you go, make more changes on the overlay and rebuild CAS. Lather, rinse, repeat.

Simply adding files to the overlay should be able to support any configuration or JSP (themes, etc) changes needed. I’ll make another post once I figure out where to put class-files for adding customized Principal-Resolver classes.