Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 5.3
Info

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.

Software

Required Software

  • A Servlet 2.4 Container - We've had good luck with Tomcat and this exercise will use that.
  • Maven2 - If you're interested in using the Maven2 WAR Overlay method, you must download the Maven software.  These instructions assume you are using a Maven 2 version which is the same level used to build all CAS modules.
  • Java 5 or higher - We'll assume you've installed a JDK. While Java 5 will work, it has reached its end-of-life, so you should install Java 6 or higher.

Recommended Software

  • An IDE - This exercise won't actually utilize an IDE, but we recommend you use the one you're most comfortable with in your daily work. We've had great luck with IntelliJ IDEA, Eclipse and the SpringSource Tool Suite
  • A Version Control system - Again, this exercise won't actually use a version control system, but you should ultimately be using one such as Subversion or Git.

Setting up the Software

Java

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

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:

...

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.

  1. Open a Command-line or Terminal window and make sure you're in your home directory.
  2. Execute the following command:

    Code Block
    keytool -genkey -alias tomcat -keyalg RSA -validity 365

...

It's recommended that you add it to the JVM keystore of your local development machine to facilitate testing.

Maven

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:

...

Info

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.

Windows

  1. Add the M2_HOME environment variable by opening up the system properties (WinKey + Pause), selecting the "Advanced" tab, and the "Environment Variables" button, then adding the M2_HOME variable in the user variables with the value $MAVEN_HOME. Be sure to omit any quotation marks around the path even if it contains spaces. Note: For Maven < 2.0.9, also be sure that the M2_HOME doesn't have a '\' as last character.
  2. In the same dialog, add the M2 environment variable in the user variables with the value %M2_HOME%\bin.
  3. Optional: In the same dialog, add the MAVEN_OPTS environment variable in the user variables to specify JVM properties, e.g. the value -Xms256m -Xmx512m. This environment variable can be used to supply extra options to Maven.
  4. In the same dialog, update/create the Path environment variable in the user variables and prepend the value %M2% to add Maven available in the command line.
  5. In the same dialog, make sure that JAVA_HOME exists in your user variables or in the system variables and it is set to the location of your JDK, e.g. C:\Program Files\Java\jdk1.5.0_02 and that %JAVA_HOME%\bin is in your Path environment variable.
  6. Open a new command prompt (Winkey + R then type cmd) and run mvn --version to verify that it is correctly installed.

Unix-based Operating Systems

  1. In a command terminal, add the M2_HOME environment variable, e.g. export M2_HOME=$MAVEN_HOME.
  2. Add the M2 environment variable, e.g. export M2=$M2_HOME/bin.
  3. Optional: Add the MAVEN_OPTS environment variable to specify JVM properties, e.g. export MAVEN_OPTS="-Xms256m -Xmx512m". This environment variable can be used to supply extra options to Maven.
  4. Add M2 environment variable to your path, e.g. export PATH=$M2:$PATH.
  5. Make sure that JAVA_HOME is set to the location of your JDK, e.g. export JAVA_HOME=/usr/java/jdk1.5.0_02 and that $JAVA_HOME/bin is in your PATH environment variable.
  6. Run mvn --version to verify that it is correctly installed.

Setting Up Your Local CAS Project

At this point, you should have all the necessary software installed.

...

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:

...

Tip

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:

Code Block
xml
xml
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd ">
	<modelVersion>4.0.0</modelVersion>
	<groupId>edu.university.cas</groupId>
	<artifactId>local-cas</artifactId>
	<packaging>war</packaging>
	<version>1.0-SNAPSHOT</version>

	<build>
		<plugins>
			<plugin>
			     <artifactId>maven-war-plugin</artifactId>
                             <configuration>
                                 <warName>cas</warName>
                             </configuration>
                        </plugin>
		</plugins>
	</build>

	<dependencies>
		<dependency>
			<groupId>org.jasig.cas</groupId>
			<artifactId>cas-server-webapp</artifactId>
			<version>${cas.version}</version>
			<type>war</type>
			<scope>runtime</scope>
		</dependency>
	</dependencies>

	<properties>
		<cas.version>3.45.10<2</cas.version>
	</properties>

        <repositories>
             <repository>
                  <id>ja-sig</id>
                  <url>http://oss.sonatype.org/content/repositories/releases/ </url>
             </repository>
        </repositories>
</project>

...

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.

Build It!

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:

...

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.

Info
titleCAS 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:

...

Next, grab the latest deployerConfigContext.xml for your release, e.g. version 3.4.10. Create 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:

...

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

Info

Copies of the original versions of each file are located in the standard distributions or can be obtained from our Subversion 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 (wink) ). 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

Messages

  • WEB-INF/classes/messages*.properties - The messages, localized.  If you don't like the default messages, you can adjust them.  Change the values for the languages you care about it.

You can add additional messages by either changing the files above, or overriding the ResourceBundleMessageSource in the cas-servlet.xml.

Views

  • WEB-INF/classes/default_views.properties - This file stores the locations of the default views (JSP pages) that CAS uses.  In general, you use should the Maven2 WAR Overlay Method to override the views rather than changing the locations.

...

The default skin is under "default". The protocols are under "protocols."

Skins

Logging

  • WEB-INF/classes/log4j.xml - The log4 settings that are used by default.  You should/could override this with your own.  Some people like to change the location of where the CAS log file is stored.

Configuration Files

All configuration files are located under WEB-INF or one of its sub-directories:

...

  • applicationContext.xml - Contains most of the default CAS beans that don't need to be changed. Includes an Autowiring Scheduler such that if you are configuring additional Quartz Jobs, they do not have to be explicitly wired, they will be detected.
  • argumentExtractorsConfiguration.xml - Configures which protocols to use. By default CAS and SAML are enabled. You would need to change this if you wanted to add Google Apps for Education support.
  • propertyFileConfigurer.xml - Configures the location of external properties. The default points to WEB-INF/cas.properties
  • securityContext.xml - This is for the security of the Services Management Tool. Usually does not need to be changed.
  • ticketExpirationPolicies.xml - The expiration policies used to expire TicketGrantingTickets and Service Tickets. Only really need to be changed if you change the timeout.
  • ticketGrantingTicketCookieGenerator.xml - The configuration for the Spring CookieGenerator for the TicketGrantingTickets. This would only be modified if you wanted to change the length of time the cookie is valid for.
  • ticketRegistry.xml - The configuration for the default ticket generator. This should be replaced if you plan on using a different TicketRegistry.
  • uniqueIdGenerators.xml - the configuration for the unique identifier generators. Normally does not need to be modified.
  • warnCookieGenerator.xml - stores the configuration for the Spring CookieGenerator for the "WARN" cookie. Should probably not be modified.

Publicly Available Maven2 WAR Overlay Examples

  • Virginia Tech maintains a sophisticated Maven War Overlay build process for its local CAS instance. The project is publicly available for review in our Subversion Repository.

 

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.

Code Block
titleExample
languagehtml/xml
<dependencies>
  <dependency>
    <groupId>org.jasig.cas</groupId>
   <artifactId>cas-management-webapp</artifactId>
   <version>${cas.version}</version>
   <type>war</type>
   <scope>runtime</scope>
  </dependency>
</dependencies>

An overlay demo for CAS server version 3.5.x : https://github.com/leleuj/cas-overlay-3.5.x.
An overlay demo for CAS server version 4.0.0 : https://github.com/leleuj/cas-overlay-demo.