EhcacheTicketRegistry
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.
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
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
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
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:
...and the Ehcache configuration itself for JGroups would be similiar to the following:
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.
<dependency> <groupId>org.jasig.cas</groupId> <artifactId>cas-server-integration-ehcache</artifactId> <version>${cas.version}</version> <!-- This should be the most recent release version of the CAS server (i.e. 3.5.2) --> <scope>compile</scope> </dependency>
JGroups dependencies
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.
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 |
Relevant JIRAs
- CAS-1076Getting issue details... STATUS