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

Icon

If you have completed implementing the JpaTicketRegistry in CAS and are having problems with the JpaTicketRegistry in production please read the section on Avoiding Deadlocks. This could likely be the source of your problem.

Overview

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.

Icon

The ticketRegistry.xml example below will only work for CAS 3.4 as it uses the Spring 3.0 schema locations. This example must be adapted to use the Spring 2.0 namespace locations for previous versions of CAS.

src/main/webapp/WEB-INF/spring-configuration/ticketRegistry.xml

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.

pom.xml (Using Maven2 WAR Overlay)
pom.xml (Not Using Maven2 WAR Overlay)

Database Configuration

JDBC Driver

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.
http://www.mysql.com/downloads/connector/j/

Download the zip file and extract the mysql-connector JAR to your $TOMCAT_HOME/lib directory.

Icon

It is not a best practice to include the JDBC driver in with your cas.war build. It is best to place the JDBC driver in your Tomcat server's lib folder.

Database Creation

If your user has sufficient privileges (do this on a test/dev tier first), on start up, the database tables should be created.

Schema Generation

Icon

The database user must have CREATE/ALTER privileges to take advantage of automatic schema generation and schema updates.

Database Modifications

Avoiding Deadlocks

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.

For MySQL Databases
For Oracle Databases

Ticket Cleanup

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.

Sample LOCKS Schema (PostgreSQL)

Platform-Specific Issues

Icon

The exact DDL to create the LOCKS table may differ from the above.  For example, on Oracle platforms the expiration_date column must be of type DATE.  Use JpaLockingStrategy, which can create and update the schema automatically, to avoid platform-specific schema issues.

 

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.

deployerConfigContext.xml

The following configuration would replace the dataSource bean found in the ticketRegistry.xml example above.

src/main/webapp/WEB-INF/deployerConfigContext.xml

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.

Virginia Tech Pool Configuration

pom.xml

In order to use c3p0, the maven dependency for the library must be included in your Maven War Overlay POM.

pom.xml

Platform-Specific Considerations

MySQL

Use InnoDB Tables

The use of InnoDB tables is strongly recommended for the MySQL platform for a couple reasons:

  • InnoDB provides referential integrity that is helpful for preventing orphaned records in ticket tables.
  • Provides better locking semantics (e.g. support for SELECT ... FOR UPDATE) than the default MyISAM table type.

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.

Sample MySQL Schema Review

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:

my.cnf
  • No labels