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