Skip to end of metadata
Go to start of metadata
Table of Contents

New CAS documentation site

Icon

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.

Overview

The University of new England (UNE) decided that with the upgrade to CAS 3.4.x, it needed to make CAS Highly-Available (HA). The requirements called for two on-campus CAS nodes to be backed up by an off-campus node. All the nodes need to recognize and validate each other's tickets. The group undertook an extensive evaluation of technologies available to facilitate clustering, and the conclusion was to use Ehcache for CAS Ticket Registry. There were many considerations, and having to write a new Ticket Registry implementation was not taken lightly. However, there exists a contribution by Cyrille Le Clerc (https://issues.jasig.org/browse/CAS-816 which led to EhCacheTicketRegistry support in the cas4 feature branch; https://issues.jasig.org/browse/CAS-1076 which will lead to EhCAcheTicketRegistry support in CAS 3.5), but that contribution has not been shipped in a released CAS server version yet

Unicon has evaluated the available code and decided to use it as the basis of the HA CAS implementation at UNE. The code was enhanced to use the latest versions of available open source libraries and to reduce reliance on Java code in favor of accomplishing the same in configuration. The rest of this document details how to add support for Ehcache-based Ticket Registry to Maven WAR Overlay-based CAS build.

Documentation

This implementation adds one Java source file and one configuration file in addition to modifying one of CAS' configuration files, ticketRegistry.xml. In fact, the ticketRegistry.xml file (included below) can replace the version supplied with CAS.

Java Code

The Java source file is adopted from the contribution by Cyrille Le Clerc. The author had a good idea to separate Ticket Granting Tickets from Service Tickets and manage them in two separate caches. This is good because of the following reasons:

  • Ticket Granting Tickets must remain valid for a long time
  • Service Tickets are short lived
  • Service Tickets must be replicated right away because the requests to validate them may very likely arrive at different CAS cluster nodes
  • Ticket Granting Tickets, as long-lived objects, may need to be spooled off to disk, as supported by Ehcache

EhCache support in CAS v3.5.x

Icon

EhCache support in CAS is now made available as part of the CAS 3.5.x release line. You will only need to apply the Java code to your CAS configuration/overlay if you are working with a release below that version.

 

Ticket Registry Configuration

The configuration file included below takes care of configuring the ticket caches and uses Ehcache to take care of ticket expiration. This results of having no need for a Ticket Registry Cleaner. It should be sufficient to use the file below as a replacement to the version that comes with CAS. Since this project uses Maven WAR Overlay build method, simply placing this file in src/main/webapp/WEB-INF/spring-configuration will result in replacing the original version. Here is the replacement ticketRegistry.xml.

 

EhCache eviction policy

Icon

There have been a few reports of cache eviction problems when tickets are expired, but haven't been removed from the cache due to ehache configuration. This can be a problem because old ticket references "hang around" in the cache despite being expired. In other words, Ehcache does inline eviction where expired objects in the cache object won't be collected from memory until the cache max size is reached or the expired entry is explicitly accessed. See http://lists.terracotta.org/pipermail/ehcache-list/2011-November/000423.html

To reclaim memory on expired tickets, cache eviction policies are must be carefully configured to avoid memory creep. Disk offload and/or a more aggressive eviction could provide a suitable workaround.

 

Ehcache Configuration

To provide Ehcache-specific configuration applicable to Ticket Registry, there is another configuration file that Ehcache uses. This file supplies some defaults to Ehcache and details to the framework how to replicate its caches. 

Active Firewall & remoteObjectPort

Icon
If you are running this on a server with active firewalls, you will probably need to specify a fixed remoteObjectPort, within the cacheManagerPeerListenerFactory.

Replication Methods

RMI (Default) 

By default the sample configuration above uses RMI to replicate the cache state. An RMI implementation is desirable because:

  • it itself is the default remoting mechanism in Java
  • it is mature
  • it allows tuning of TCP socket options
  • Element keys and values for disk storage must already be Serializable, therefore directly transmittable over RMI without the need for conversion to a third format such as XML.
  • It can be configured to pass through firewalls
  • RMI had improvements added to it with each release of Java, which can then be taken advantage of.

Ehcache provides replicated caching using RMI. To set up RMI replicated caching, you need to configure the CacheManager with a PeerProvider and a CacheManagerPeerListener. Then for each cache that will be replicated, you need to add one of the RMI cacheEventListener types to propagate messages. You can also optionally configure a cache to bootstrap from other caches in the cluster. See this link  for additional information.

JGroups

JGroups can be used as the underlying mechanism for the replication operations in Ehcache. JGroups offers a very flexible protocol stack, reliable unicast, and multicast message transmission. To set up replicated caching using JGroups, you need to configure a PeerProviderFactory. For each cache that will be replicated, you then need to add a cacheEventListenerFactory to propagate messages.

The ticket registry configuration based on JGroups would look similiar to the following snippet:

JGroups Ticket Registry  Expand source

...and the Ehcache configuration itself for JGroups would be similiar to the following:

Ehcache JGroups configuration  Expand source


Maven Dependencies

Normally, the Maven war overlay project may not need to have any compile dependencies. Since this project does, these dependencies had to be added. See the attached pom.xml file for the additions. Keep in mind, however, that this file contains some UNE-specific additions that your implementation will not need. Also, be aware that the extensive list of exclusions targeted to eliminate duplicate versions of dependent jar files resulting from using Maven WAR Overlay will need to be modified when using different version of CAS or ClearPass.

JGroups dependencies

Icon

If you are using JGroups as the replication method, please ensure that you're overlay is configured to retrieve the following dependencies as well:

 

File Locations

The table below lists the locations where each of the files should be deposited.

Icon
If you're on CAS 3.5.0 or later, you do not need to apply the files below manually to your overlay. The ticket registry Java class is available via the "cas-server-integration-ehcache" module declared through the dependency. Just apply the configuration to your overlay.

File

Directory

EhcacheTicketRegistry.java

src/main/java/org/jasig/cas/ticket/registry

ticketRegistry.xml

src/main/webapp/WEB-INF/spring-configuration

ehcache-replicated.xml

src/main/webapp/WEB-INF

  File Modified
XML File pom.xml Feb 16, 2011 by Adam Rybicki
Java Source EhcacheTicketRegistry.java Feb 16, 2011 by Adam Rybicki

Relevant JIRAs

CAS-1076 - ehcache based TicketRegistry for CAS3.x Resolved

CAS-816 - Proposal : EH Cache based distributed TicketRegistry Closed

CAS-1050 - EH Cache based distributed TicketRegistry Closed

  • No labels