WORKERS AHEAD!
You are viewing the development documentation for the Apereo CAS server. The functionality presented here is not officially released yet. This is a work in progress and will be continually updated as development moves forward. You are most encouraged to test the changes presented.
To view the documentation for a specific Apereo CAS server release, please choose an appropriate version. The release schedule is available here.JPA Service Registry
Stores registered service data in a database.
Support is enabled by adding the following module into the overlay:
implementation "org.apereo.cas:cas-server-support-jpa-service-registry:${project.'cas.version'}"
<dependency>
<groupId>org.apereo.cas</groupId>
<artifactId>cas-server-support-jpa-service-registry</artifactId>
<version>${cas.version}</version>
</dependency>
dependencyManagement {
imports {
mavenBom "org.apereo.cas:cas-server-support-bom:${project.'cas.version'}"
}
}
dependencies {
implementation "org.apereo.cas:cas-server-support-jpa-service-registry"
}
To learn how to configure database drivers, please see this guide.
Control global properties that are relevant to Hibernate, when CAS attempts to employ and utilize database resources, connections and queries.
cas.jdbc.case-insensitive=false
When choosing physical table names, determine whether names should be considered case-insensitive. |
cas.jdbc.gen-ddl=true
Whether to generate DDL after the EntityManagerFactory has been initialized creating/updating all relevant tables. |
cas.jdbc.physical-table-names=
Indicate a physical table name to be used by the hibernate naming strategy in case table names need to be customized for the specific type of database. The key here indicates the CAS-provided table name and the value is the translate physical name for the database. If a match is not found for the CAS-provided table name, then that name will be used by default. |
cas.jdbc.show-sql=false
Whether SQL queries should be displayed in the console/logs. |
Note that the default value for Hibernate’s DDL setting is create-drop
which may not be appropriate
for use in production. Setting the value to validate
may be more desirable, but any of the following options can be used:
Type | Description |
---|---|
validate |
Validate the schema, but make no changes to the database. |
update |
Update the schema. |
create |
Create the schema, destroying previous data. |
create-drop |
Drop the schema at the end of the session. |
none |
Do nothing. |
Note that during a version migration where any schema has changed create-drop
will result
in the loss of all data as soon as CAS is started. For transient data like tickets this is probably
not an issue, but in cases like the audit table important data could be lost. Using update
, while safe
for data, is confirmed to result in invalid database state. validate
or none
settings
are likely the only safe options for production use.
For more information on configuration of transaction levels and propagation behaviors, please review this guide.
Container-based JDBC Connections
If you are planning to use a container-managed JDBC connection with CAS (i.e. JPA Ticket/Service Registry, etc)
then you can set the data-source-name
property on any of the configuration items that require a database
connection. When using a container configured data source, many of the pool related parameters will not be used.
If data-source-name
is specified but the JNDI lookup fails, a data source will be created with the configured
(or default) CAS pool parameters.
If you experience classloading errors while trying to use a container datasource, you can try
setting the data-source-proxy
setting to true which will wrap the container datasource in
a way that may resolve the error.
The data-source-name
property can be either a JNDI name for the datasource or a resource name prefixed with
java:/comp/env/
. If it is a resource name then you need an entry in a web.xml
that you can add to your
CAS overlay. It should contain an entry like this:
1
2
3
4
5
<resource-ref>
<res-ref-name>jdbc/casDataSource</res-ref-name>
<res-type>javax.sql.DataSource</res-type>
<res-auth>Container</res-auth>
</resource-ref>
In Apache Tomcat, a container datasource can be defined like this in the context.xml
:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
<Resource name="jdbc/casDataSource"
auth="Container"
type="javax.sql.DataSource"
driverClassName="org.postgresql.Driver"
url="jdbc:postgresql://casdb.example.com:5432/xyz_db"
username="cas"
password="xyz"
testWhileIdle="true"
testOnBorrow="true"
testOnReturn="false"
validationQuery="select 1"
validationInterval="30000"
timeBetweenEvictionRunsMillis="30000"
factory="org.apache.tomcat.jdbc.pool.DataSourceFactory"
minIdle="0"
maxIdle="5"
initialSize="0"
maxActive="20"
maxWait="10000" />
In Jetty, a pool can be put in JNDI with a jetty.xml
or jetty-env.xml
file like this:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
<?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd">
<Configure class="org.eclipse.jetty.webapp.WebAppContext">
<New id="datasource.cas" class="org.eclipse.jetty.plus.jndi.Resource">
<Arg></Arg> <!-- empty scope arg is JVM scope -->
<Arg>jdbc/casDataSource</Arg> <!-- name that matches resource in web.xml-->
<Arg>
<New class="org.apache.commons.dbcp.BasicDataSource">
<Set name="driverClassName">oracle.jdbc.OracleDriver</Set>
<Set name="url">jdbc:oracle:thin:@//casdb.example.com:1521/ntrs"</Set>
<Set name="username">cas</Set>
<Set name="password">xyz</Set>
<Set name="validationQuery">select dummy from dual</Set>
<Set name="testOnBorrow">true</Set>
<Set name="testOnReturn">false</Set>
<Set name="testWhileIdle">false</Set>
<Set name="defaultAutoCommit">false</Set>
<Set name="initialSize">0</Set>
<Set name="maxActive">15</Set>
<Set name="minIdle">0</Set>
<Set name="maxIdle">5</Set>
<Set name="maxWait">2000</Set>
</New>
</Arg>
</New>
</Configure>
Auto Initialization
Upon startup and configuration permitting, the registry is able to auto initialize itself from default JSON service definitions available to CAS. See this guide for more info.