The JPA Ticket Registry allows CAS to store client authenticated state data (tickets) in a database back-end such as MySQL.
The JPA Ticket Registry allows CAS to store client authenticated state
data (tickets) in a database back-end such as MySQL.
<divclass="alert alert-warning"><strong>Usage Warning!</strong><p>Using a RDBMS as the back-end persistence choice for Ticket Registry state management is a fairly unnecessary and complicated process. Ticket registries generally do not need the durability that comes with RDBMS and unless you are already outfitted with clustered RDBMS technology and the resources to manage it, the complexity is likely not worth the trouble. Given the proliferation of hardware virtualization and the redundancy and vertical scaling they often provide, more suitable recommendation would be the default in-memory ticket registry for a single node CAS deployment and distributed cache-based registries for higher availability.</p></div>
<divclass="alert alert-warning"><strong>Usage Warning!</strong><p>Using a RDBMS as
the back-end persistence choice for Ticket Registry state management is a fairly unnecessary and complicated
process. Ticket registries generally do not need the durability that comes with RDBMS and unless
you are already outfitted with clustered RDBMS technology and the resources to manage it,
the complexity is likely not worth the trouble. Given the proliferation of hardware virtualization
and the redundancy and vertical scaling they often provide, more suitable recommendation would be
the default in-memory ticket registry for a single node CAS deployment and distributed cache-based
registries for higher availability.</p></div>
# Configuration
# Configuration
...
@@ -15,6 +23,25 @@ The JPA Ticket Registry allows CAS to store client authenticated state data (tic
...
@@ -15,6 +23,25 @@ The JPA Ticket Registry allows CAS to store client authenticated state data (tic
- Adjust the `src/main/webapp/WEB-INF/spring-configuration/ticketRegistry.xml` with the following:
- Adjust the `src/main/webapp/WEB-INF/spring-configuration/ticketRegistry.xml` with the following:
The above snippet assumes that data source information and connection details are defined.
- Configure other JPA dependencies:
- Configure other JPA dependencies:
In the `pom.xml` file of the Maven overlay, adjust for the following dependencies:
{% highlight xml %}
...
<dependency>
<groupId>org.hibernate</groupId>
<artifactId>hibernate-core</artifactId>
<version>${hibernate.core.version}</version>
<scope>runtime</scope>
</dependency>
<dependency>
<groupId>org.hibernate</groupId>
<artifactId>hibernate-entitymanager</artifactId>
<version>${hibernate.core.version}</version>
<scope>runtime</scope>
</dependency>
...
{% endhighlight %}
##Cleaner Locking Strategy
##Cleaner Locking Strategy
The above shows a JPA 2.0 implementation of an exclusive, non-reentrant lock, `JpaLockingStrategy`, to be used with the JPA-backed ticket registry.
The above shows a JPA 2.0 implementation of an exclusive, non-reentrant lock,
`JpaLockingStrategy`, to be used with the JPA-backed ticket registry.
This will configure the cleaner with the following defaults:
This will configure the cleaner with the following defaults:
...
@@ -112,16 +137,23 @@ This will configure the cleaner with the following defaults:
...
@@ -112,16 +137,23 @@ This will configure the cleaner with the following defaults:
# Database Configuration
# Database Configuration
## JDBC Driver
## JDBC Driver
CAS must have access to the appropriate JDBC driver for the database. Once you have obtained the appropriate driver and configured the data source, place the JAR inside the lib directory of your web server environment (i.e. `$TOMCAT_HOME/lib`)
CAS must have access to the appropriate JDBC driver for the database. Once you have obtained
the appropriate driver and configured the data source, place the JAR inside the lib directory
of your web server environment (i.e. `$TOMCAT_HOME/lib`)
## Schema
## Schema
If the user has sufficient privileges on start up, the database tables should be created. The database user MUST have `CREATE/ALTER` privileges to take advantage of automatic schema generation and schema updates.
If the user has sufficient privileges on start up, the database tables should be created.
The database user MUST have `CREATE/ALTER` privileges to take advantage of automatic
schema generation and schema updates.
## Deadlocks
## Deadlocks
The Hibernate SchemaExport DDL creation tool *may* fail to create two very import indices when generating the ticket tables. The absence of these indices dramatically increases the potential for database deadlocks under load.
The Hibernate SchemaExport DDL creation tool *may* fail to create two very import indices
If the indices were not created you should manually create them before placing your CAS configuration into a production environment.
when generating the ticket tables. The absence 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.
To review indices, you may use the following MYSQL-based sample code below:
To review indices, you may use the following MYSQL-based sample code below:
...
@@ -155,7 +187,10 @@ CREATE INDEX "TGT_TGT_FK_I"
...
@@ -155,7 +187,10 @@ CREATE INDEX "TGT_TGT_FK_I"
## Ticket Cleanup
## Ticket Cleanup
The use `JpaLockingStrategy` is strongly recommended for HA environments where multiple nodes are attempting ticket cleanup on a shared database. `JpaLockingStrategy` can auto-generate the schema for the target platform. A representative schema is provided below that applies to PostgreSQL:
The use `JpaLockingStrategy` is strongly recommended for HA environments where
multiple nodes are attempting ticket cleanup on a shared database.
`JpaLockingStrategy` can auto-generate the schema for the target platform.
A representative schema is provided below that applies to PostgreSQL:
{% highlight sql %}
{% highlight sql %}
...
@@ -169,37 +204,17 @@ ALTER TABLE locks ADD CONSTRAINT pk_locks
...
@@ -169,37 +204,17 @@ ALTER TABLE locks ADD CONSTRAINT pk_locks
PRIMARY KEY (application_id);
PRIMARY KEY (application_id);
{% endhighlight %}
{% endhighlight %}
<divclass="alert alert-warning"><strong>Platform-Specific Issues</strong><p>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 `DAT`E. Use the `JpaLockingStrategy` which can create and update the schema automatically to avoid platform-specific schema issues.</p></div>
<divclass="alert alert-warning"><strong>Platform-Specific Issues</strong><p>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 `DAT`E. Use the `JpaLockingStrategy`
which can create and update the schema automatically to avoid platform-specific schema issues.</p></div>
## Connection Pooling
## 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, which would replace the `dataSource` bean found in the `ticketRegistry.xml` example above:
It is ***strongly*** recommended that database connection pooling be used in a p
production environment. Based on the example above, the following pool configuration parameters are provided
{% highlight xml %}
for information only and may serve as a reasonable starting point for configuring a production database connection pool.
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.
<divclass="alert alert-info"><strong>Usage Tip</strong><p>Note the health check query is specific to PostgreSQL.</p></div>
<divclass="alert alert-info"><strong>Usage Tip</strong><p>Note the health check query is specific to PostgreSQL.</p></div>
