New CAS documentation site
CAS documentation has moved over to apereo.github.io/cas, starting with CAS version 4.x. The wiki will no longer be maintained. For the most recent version of the documentation, please refer to the aforementioned link.
This document is designed to walk a new CAS user through our recommended development/build process. It does not require you to explicitly download any version of CAS, but it does require particular development tools to be available. We've detailed those requirements and our recommendations as part of this process. Experienced users may be able to ignore that, and other parts. At the end of the document, we've listed publicly available examples of our recommended process. This document will continue to evolve.
Setting up the Software
You should download the Java SDK from the link above and follow its installation prompts. The installation methods will vary per operating system so they won't be described here.
Tomcat is relatively simple to set up, especially for CAS. At the time of this writing, the most recent version was Tomcat 7.0.22, so that's the version we'll work with. You can download it from the Tomcat web site. We recommend downloading the core zip or tar.gz. You should use your favorite program to unzip the file to a location. For the purpose of this exercise, we'll install Tomcat 7.0.22 to the following location:
You can install it wherever you want, though we recommend you don't utilize a directory with spaces. To make life easier, from this point forward, we'll refer to the Tomcat home, as $TOMCAT_HOME in case you use a different directory.
From this point forward, the documentation will refer to the location of your Tomcat home directory as $TOMCAT_HOME
We can run our examples without SSL enabled, but you should never really do that. Therefore, we'll step through setting up Tomcat's keystore file with a self-signed certificate. Self-signed certificates should NEVER be used for anything beyond development. Your test environment's certificate SHOULD mirror that of your production environment.
Note, these instructions assume you've never set up the keystore before. If you have, you will need to delete any key with the alias "tomcat". These instructions also assume the Java executables are in your path.
Create the Certificate.
NOTE, the validity parameter allows you to specify, in the number of days, how long the certificate should be valid for. The longer the time period, the less likely you are to need to recreate it. To recreate it, you'd need to delete the old one and then follow these instructions again.
The response will look something like this:
For the keystore password you should enter "changeit" without the quotation marks. When prompted for the first and last name, you should enter your machine name during development. The rest of the data does not matter. Then obviously answer "yes" to the question of whether it's correct.
Next, open up $TOMCAT_HOME/conf/server.xml and locate the block that looks like this:
Remove the <!-- and the --> to enable the SSL connection. Then save the file. If you have Tomcat started, you'll need to restart it to enable the additional connector. You should then able able to access Tomcat over:
Any application that wishes to securely connect to this Tomcat instance would need to import the certificate. You can export the certificate that's compatible with other JVM keystores by executing the following command:
You'll get output that looks similar to this:
You can then import the server.crt into other JVM keystore's by executing a command similar to this:
Your JVM cacerts file is located in an obscure location. We believe it's /System/Library/Frameworks/JavaVM.framework/Versions/CurrentJDK/Home/lib/security but you should confirm that.
It's recommended that you add it to the JVM keystore of your local development machine to facilitate testing.
Maven is another Apache project, and it's also easy to install. Similar to Tomcat, you should download Maven from its web site and unzip it. For purposes of this tutorial, we'll assume you've installed the latest Maven 2 version to:
For sanity's sake, we'll refer to the location of the Maven2 installation as $MAVEN_HOME in case you use a different location.
From this point forward, the documentation will refer to the location of your Maven2 home directory as $MAVEN_HOME.
Macintosh Users: You've already got a version of Maven installed by default. If you're interested in upgrading your version of Maven, check out these instructions.
Unix-based Operating Systems
Setting Up Your Local CAS Project
At this point, you should have all the necessary software installed.
Working with a Maven2-based project may be different from when you worked with an Ant-based project. For many people, Ant-based projects included things like manually managing dependencies, building source for external projects that you were integrating with, keeping binary JAR files in your version control system, and manually crafting Ant build files. Maven2 is a different way of thinking. The libraries or projects you're working with maintain the list of required dependencies, Maven2 attempts to resolve them and any conflicts, downloads them and keeps them in a local cache. It also uses standard "goals" (which were often called tasks in Ant). Recent versions of Ant have included some of these features with add-ons such as Ivy 2.0. At this point, there is no expectation that you understand completely how Maven2 works. We'll explain the important concepts as we go along.
In particular for CAS, we'll be working with what's called a "WAR Overlay." Essentially, we've already built and made available the standard CAS distribution. What you're interested in doing is merely ADDING to our standard distribution, possibly by adding new files or configuration, new dependencies, or replacing a few of our standard files. This WAR Overlay process supports them all. We always recommend this process because if keeps you out of the business of downloading the CAS source, building it, making your customizations, rebuilding it, etc. and maintaining a copy of our source code locally. With the WAR overlay, you're only keeping the files you care about locally.
How do we get started?
The first step is to create your "workspace." We'll assume, for arguments sake, that we're not using an IDE since it makes this tutorial easier, and we're not working with many files. We'll assume you're keeping a copy of your work here:
In case you're not, we'll refer to your work area as $WORKSPACE.
In case you're keeping your local work elsewhere, we'll refer to your workspace as $WORKSPACE
This means that if you're creating your local organization's CAS project, you might put the files here:
We'll refer to this as $PROJECT_HOME to make it easier.
We'll refer to your local project's directory as $PROJECT_HOME
Create the pom.xml
The second step is to create the pom.xml for your local institution's CAS. This should go in the $PROJECT_HOME directory. We recommend you create a version like the one below:
Let's walk through this step by step:
This is the standard POM root xml element. Suffice to say, we must have it for this to be useful! The Maven Team maintains a relatively robust POM reference if you're interested in learning more about the POM.
The next set of elements are:
The modelVersion MUST be set to 4.0.0. The groupId should be set to something that refers to your local organization. The artifactId should reflect that it's a local instance of CAS (i.e. local-cas, local-cas-webapp, myU-cas-webapp, etc.). Since we ultimately want to build a WAR file to deploy, our packaging should be set to war. Finally, the version should reflect your local organization's versioning system for local CAS releases.
The next set of elements are:
This section relates to how we want to build the project. We're saying that when we tell Maven2 to build the project, the WAR plugin should be used with the supplied configuration. In this instance, our configuration only says what to name the WAR file. For more information on the WAR Plugin, take a look at its documentation.
The next set of elements are:
This section is critical. Its where you define what libraries and external projects YOUR project depends on. In this particular POM file, our only dependency is the Jasig produced WAR file for CAS. Later on, we'll see why you might need more. Notice that each dependency is referenced by an artifactId and a groupId. Maven attempts to automatically resolve dependencies from publicly available repositories AND whatever repositories you've defined in your POM. In our case, we had added this:
This tells Maven2 to not only look in the public repositories that Maven2 knows about, but also to check in the Jasig repository (which is where you'll find the Jasig CAS Server artifacts).
The final item we have in our project is a small section where we can define custom properties. In this instance, we've defined the cas.version which is referenced in our CAS Web App dependency. This is not necessary at all, but it allows us to see quickly at a glance all the dependency version numbers.
While this project is not yet exceptionally useful, we should make sure we can build it. As mentioned before, Maven2 defines a set of "goals" that have common meaning across projects. To build our WAR file, execute the following in the $PROJECT_HOME directory:
What does this mean?
If the build was successful, you should now see a directory called "target" in your $PROJECT_HOME. This directory should have a cas.war in it. Again, it's not a terribly useful WAR file right now. You could have just taken the standard CAS artifact from the Maven repository and renamed it and had the same thing. Baby steps! The next step is to deploy it to Tomcat. Copy the file to $TOMCAT_HOME/webapps/ Then, start Tomcat. On Unix-based systems, there should be a startup.sh in the $PROJECT_HOME/bin directory. Windows users should see a similar batch file. If you then point your browser to https://$FULL_MACHINE_NAME:8443/cas/login*, you should see the CAS login page. The default authentication is such that the username and the password are the same. Once you're done playing with it, you can stop it by using either *$PROJECT_HOME/bin/shutdown.sh or shutdown.bat.
CAS 4 Default Authentication
Starting with CAS 4, the default authentication handler has been switched to a slightly more complicated handler. Briefly, the username and password are no longer the same, but are actually changed to a hardcoded set in the configuration. The username is "casuser" in lowercase without the quotes and the password is "Mellon", without the quotes of course.
See this link for more info.
Replace the Default Authentication Method with Something Else
CAS includes a large number of authentication methods, all of which are detailed under Authentication so we won't reiterate them here. We're going to replace the default authentication method with one of them. To keep this simple, we're going to use one that doesn't require any external resources (such as an LDAP server). Not entirely realistic, but the mechanism is the same. In this case, we'll be using one of the "generic" authentication handlers. Therefore, the first step is add a dependency to the pom.xml. So if you've closed out of your pom.xml, open it back up! Add the following dependency into the <dependencies>...</dependencies> XML block:
This says that we want to include the Generic Support from CAS at Runtime, and that it's a JAR file. Next, we'll need to configure this in! Remember when we said this was the Maven2 WAR Overlay method, and that this means that you can selectively overwrite files in the "WAR" that you're laying stuff over. Well, the WAR dependency is the one we're going to overlay stuff into. So under project home create the following directory structure:
which is where we'll be putting our custom configuration.
Next, grab the latest deployerConfigContext.xml for your release, e.g. version 3.5.2 Create a deployerConfigContext.xml in $PROJECT_HOME/src/main/webapp/WEB-INF/ and copy in the contents from the web. Next locate this bean:
This is the simple test authentication method that always resolve to username=password for demonstration purposes. Clearly, not a good thing to have in production. Well, what we're going to replace it with isn't necessarily the greatest thing for production either, but it's a simple step up. Replace the above bean definition with:
This example authentication method only accepts the user "scott" if his supplied password is "secret". Clearly not useful in production either, but slightly more secure. With this change in place, save the file. Rebuild your WAR file from the $PROJECT_HOME:
Copy that WAR file into the $TOMCAT_HOME/webapps/. Delete any existing "cas" directory under $TOMCAT_HOME/webapps/. Start up your container again. Navigate to the login page. When prompted for the username and password, first try entering "scott" and "scott". This should fail. Then enter "scott" and "secret". You should see the message that says you've successfully logged in. You've made a great first attempt at modifying your CAS installation.
While this is a simple case, you can configure in more complex authentication methods. As of this writing, CAS supports database, LDAP, Active Directory, SPNEGO, Delegated/Trusted, X.509 Certificates, and more. Some methods are more complex than others, and we've made attempts to document them in their appropriate pages. The above example should give you the starting point for configuring other authentication methods, but remember, they're all not that easy, but they follow the same steps: add the dependency, update the appropriate configuration files, and rebuild.
Modifying the Look and Feel
Spring Configuration Structure
Copies of the original versions of each file are located in the standard distributions or can be obtained from our Github Repository
Because we would like to encourage the usage of the Maven2 WAR Overlay method, we've made numerous attempts to make it easier to use. One of those methods includes more fine-grained Spring XML configuration files, as well as a method for auto-loading your additional custom XML files. We're going to go over this now:
Loading Additional Configuration Files and Enabling Additional Features
CAS will automatically load any XML file located in $PROJECT_HOME/src/main/webapp/WEB-INF/spring-configuration/ (after obviously, rebuilding the WAR ). So when you have your own configuration to add, or you want to enable another feature for CAS, you can drop the XML file in that directory and it will load. You can see this example with our Inspektr configuration and the ClearPass Extension.
Many of the optional CAS features are built to be enabled this way (i.e. the Inspektr library).
Explanation of Location of Files in the Standard Distribution
You can add additional messages by either changing the files above, or overriding the ResourceBundleMessageSource in the cas-servlet.xml.
To add additional views, one can either customize the provided properties or provide your own view resolver in a separate Spring configuration file, such as this example:
The files are for the most part located under WEB-INF/view/jsp.
The default skin is under "default". The protocols are under "protocols."
All configuration files are located under WEB-INF or one of its sub-directories:
Configuration Files under the WEB-INF/spring-configuration directory:
Publicly Available Maven2 WAR Overlay Examples
Services management webapp
Before CAS server 4.0.0, the services management webapp was part of the CAS server.
But with the new major version 4.0.0 of CAS, the services management webapp is in a more general and separate webapp dedicated to CAS management : the cas-management-webapp module.
As it requires equivalent configuration in the deployerConfigContext.xml file as the CAS server webapp, the CAS management webapp needs to be setup using the Maven2 WAR Overlay Method, in a similar way as the CAS server.