The JpaTicketRegistry allows CAS to store client authenticated state data (tickets) in a database back-end such as MySQL. This is useful for creating highly available (HA) CAS clusters consisting of multiple application nodes such as Tomcat.
This guide will help you configure the JpaTicketRegistry in CAS. While the documentation provided primarily focuses on connecting the JpaTicketRegistry to MySQL, with some modification this information should provide a good start for connecting to other database back-ends as well.
Spring Configuration (ticketRegistry.xml)
This is where the bulk of your configuration for the JpaTicketRegistry goes.
If you're using the Maven2 WAR Overlay process then you will need to create this file in the src/main/webapp/WEB-INF/spring-configuration folder of your project directory.
If you're not using the Maven2 WAR Overlay process then you can edit this file in the cas-server-webapp/src/main/webapp/WEB-INF/spring-configuration folder of the CAS source tree.
Be sure to replace the dataSource information with your own. You may reference other data sources external to this file. For example, if you define an entityManagerFactory, transactionManager and dataSource in deployerConfigContext.xml, e.g., for the services registry, then there's no need to enter those here.
Persistence Configuration with Spring 3.1
If you're using Spring 3.1 and above in your CAS overlay and your persistence configuration involves using only one unit, you might be able to reduce your configuration by taking advantages of the Spring 3.1's new "packagesToScan" property. For more information on Spring functionality, please review this document,item 3.12. If you're interested to see this configuration in action, please review the code used for unit tests of the CAS project at this link.
Configuring JPA Dependencies
In order for the JpaTicketRegistry to work you will need to add hibernate-core and hibernate-entitymanager to the dependencies listed in your pom.xml file.
If you're using the Maven2 WAR Overlay process then your pom.xml file should be in the root of your project directory. The hibernate.core.version property will need to be set by looking at the root POM of your CAS version's source tree.
If you're not using the Maven2 WAR Overlay process you can edit this file in the cas-server-webapp folder of the CAS source tree. The hibernate.core.version property should be picked up automatically from the root POM.
CAS must have access to the appropriate JDBC driver for your database. The example in the ticketRegistry.xml depends on the MySQL JDBC Driver.
You can download the MySQL JDBC Driver from the MySQL developers website.
Download the zip file and extract the mysql-connector JAR to your $TOMCAT_HOME/lib directory.
If your user has sufficient privileges (do this on a test/dev tier first), on start up, the database tables should be created.
In some cases the Hibernate SchemaExport DDL creation tool will fail to create two very import indices when generating the ticket tables. The adbsence of these indices dramatically increases the potential for database deadlocks under load.
If the indices were not created you should manually create them before placing your CAS configuration into a production environment.
The following is an example of what you should find in MySQL when checking for these indices.
If you find the indices are missing the following SQL commands should create them.
The use of either JpaLockingStrategy or JdbcLockingStrategy (deprecated as of 3.4.11) is strongly recommended for HA environments where multiple nodes are attempting ticket cleanup on a shared database. The LOCKS table must be created manually if using JdbcLockingStrategy. (JpaLockingStrategy can auto-generate schema for the target platform.) A representative schema is provided below.
Database Connection Pooling
It is strongly recommended that database connection pooling be used in a production environment. The following configuration makes use of the c3p0 connection pooling library. Virginia Tech has used this connection pooling library in preference to the Apache Jakarta project's commons-dbcp library in production for months as of this writing (2010-01-20) and have been very pleased with performance and configurability.
The following configuration would replace the dataSource bean found in the ticketRegistry.xml example above.
The following pool configuration parameters are provided for information only and may serve as a reasonable starting point for configuring a production database connection pool. Note the health check query is specific to PostgreSQL.
In order to use c3p0, the maven dependency for the library must be included in your Maven War Overlay POM.
Use InnoDB Tables
The use of InnoDB tables is strongly recommended for the MySQL platform for a couple reasons:
InnoDB tables are easily specified via the use of the following Hibernate dialect:
BLOB vs LONGBLOB
Hibernate on recent versions of MySQL (e.g. 5.1) properly map the @Lob JPA annotation onto type LONGBLOB, which is very important since these fields commonly store serialized graphs of Java objects that grow proportionally with CAS SSO session lifetime. Under some circumstances, e.g. old versions of MySQL prior to 5.1, Hibernate may treat these columns as type BLOB, which have storage limits that are easily exceeded. It is recommended that the generated schema be reviewed and any BLOB type columns be converted to LONGBLOB.
In the example above you can see that column SERVICES_GRANTED_ACCESS_TO in the TICKETGRANTINGTICKET table is set to BLOB. The following MySQL statement would change this column's type to LONGBLOB.
Case Sensitive Schema
It may necessary to force lowercase schema names in the MySQL configuration: