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.

JDBC Drivers

While in most cases this is unnecessary and handled by CAS automatically, you may need to also include the following module to account for various database drivers:

<dependency>
    <groupId>org.apereo.cas</groupId>
    <artifactId>cas-server-support-jdbc-drivers</artifactId>
    <version>${cas.version}</version>
</dependency>

implementation "org.apereo.cas:cas-server-support-jdbc-drivers:${project.'cas.version'}"

dependencyManagement {
    imports {
        mavenBom "org.apereo.cas:cas-server-support-bom:${project.'cas.version'}"
    }
}

dependencies {
    implementation "org.apereo.cas:cas-server-support-jdbc-drivers"
}

dependencies {
    /*
        The following platform references should be included automatically and are listed here for reference only.

        implementation enforcedPlatform("org.apereo.cas:cas-server-support-bom:${project.'cas.version'}")
        implementation platform(org.springframework.boot.gradle.plugin.SpringBootPlugin.BOM_COORDINATES)
        
    */
    implementation "org.apereo.cas:cas-server-support-jdbc-drivers"
}

JPA Implementations

The following JPA implementations are provided by CAS. In most cases, the indicated modules do not need to be included in a CAS build and the implementation would be automatically chosen by the feature module. The details below are listed for reference and may be of use in advanced scenarios where development may be required.

Hibernate

Hibernate ORM is an object–relational mapping tool for the Java programming language. It provides a framework for mapping an object-oriented domain model to a relational database.

<dependency>
    <groupId>org.apereo.cas</groupId>
    <artifactId>cas-server-support-jpa-hibernate</artifactId>
    <version>${cas.version}</version>
</dependency>

implementation "org.apereo.cas:cas-server-support-jpa-hibernate:${project.'cas.version'}"

dependencyManagement {
    imports {
        mavenBom "org.apereo.cas:cas-server-support-bom:${project.'cas.version'}"
    }
}

dependencies {
    implementation "org.apereo.cas:cas-server-support-jpa-hibernate"
}

dependencies {
    /*
        The following platform references should be included automatically and are listed here for reference only.

        implementation enforcedPlatform("org.apereo.cas:cas-server-support-bom:${project.'cas.version'}")
        implementation platform(org.springframework.boot.gradle.plugin.SpringBootPlugin.BOM_COORDINATES)
        
    */
    implementation "org.apereo.cas:cas-server-support-jpa-hibernate"
}

EclipseLink

EclipseLink is the open source Eclipse Persistence Services Project from the Eclipse Foundation. The software provides an extensible framework that allows Java developers to interact with various data services, including databases, web services, Object XML mapping, and enterprise information systems.

<dependency>
    <groupId>org.apereo.cas</groupId>
    <artifactId>cas-server-support-jpa-eclipselink</artifactId>
    <version>${cas.version}</version>
</dependency>

implementation "org.apereo.cas:cas-server-support-jpa-eclipselink:${project.'cas.version'}"

dependencyManagement {
    imports {
        mavenBom "org.apereo.cas:cas-server-support-bom:${project.'cas.version'}"
    }
}

dependencies {
    implementation "org.apereo.cas:cas-server-support-jpa-eclipselink"
}

dependencies {
    /*
        The following platform references should be included automatically and are listed here for reference only.

        implementation enforcedPlatform("org.apereo.cas:cas-server-support-bom:${project.'cas.version'}")
        implementation platform(org.springframework.boot.gradle.plugin.SpringBootPlugin.BOM_COORDINATES)
        
    */
    implementation "org.apereo.cas:cas-server-support-jpa-eclipselink"
}

Database Support

Automatic support for drivers includes the following databases. All other drivers need to be manually added to the build configuration.

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.

_{How can I configure this property?}

Configuration properties can be included and activated using the following strategies.

Note

When possible, properties should be stored in lower-case kebab format, such as cas.property-name=value. The only possible exception to this rule is when naming actuator endpoints; The name of the actuator endpoints (i.e. ssoSessions) MUST remain in camelCase mode.

CAS properties can be specified using the Java configuration property syntax in any and all .properties files:

cas.jdbc.case-insensitive=...

This is the most common form of property configuration that is recognized by CAS, regardless of the actual property source, which might in fact be managed separately outside the CAS environment, by another system or cloud framework.

CAS properties can be specified using the YAML syntax:

cas: 
  jdbc: 
    case-insensitive: "..."

Note that YAML is very specific about structure and indentation. Be sure to verify the correctness of the final result with your YAML validator of choice.

CAS properties can be passed to the CAS web application as system properties, when the application is launched:

java -Dcas.jdbc.case-insensitive="..." -jar build/libs/cas.war

The above example assumes that the CAS web application is packaged as cas.war with an embedded server container and can be found in the build/libs directory. Note the placement of the system property which must be specified before the CAS web application is launched.

CAS properties can specified as system environment variables before the CAS web application is launched:

export CAS_JDBC_CASE_INSENSITIVE="..."

java -jar build/libs/cas.war

The above example assumes that the CAS web application is packaged as cas.war with an embedded server container and can be found in the build/libs directory.

CAS properties can be passed to the CAS web application as command-line arguments, when the application is launched:

java -jar build/libs/cas.war --cas.jdbc.case-insensitive="..."

The above example assumes that the CAS web application is packaged as cas.war with an embedded server container and can be found in the build/libs directory.

cas.jdbc.gen-ddl=true

Whether to generate DDL after the EntityManagerFactory has been initialized creating/updating all relevant tables.

_{How can I configure this property?}

Configuration properties can be included and activated using the following strategies.

Note

CAS properties can be specified using the Java configuration property syntax in any and all .properties files:

cas.jdbc.gen-ddl=true

CAS properties can be specified using the YAML syntax:

cas: 
  jdbc: 
    gen-ddl: "true"

Note that YAML is very specific about structure and indentation. Be sure to verify the correctness of the final result with your YAML validator of choice.

CAS properties can be passed to the CAS web application as system properties, when the application is launched:

java -Dcas.jdbc.gen-ddl="true" -jar build/libs/cas.war

CAS properties can specified as system environment variables before the CAS web application is launched:

export CAS_JDBC_GEN_DDL="true"

java -jar build/libs/cas.war

The above example assumes that the CAS web application is packaged as cas.war with an embedded server container and can be found in the build/libs directory.

CAS properties can be passed to the CAS web application as command-line arguments, when the application is launched:

java -jar build/libs/cas.war --cas.jdbc.gen-ddl="true"

The above example assumes that the CAS web application is packaged as cas.war with an embedded server container and can be found in the build/libs directory.

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.

_{How can I configure this property?}

Configuration properties can be included and activated using the following strategies.

Note

CAS properties can be specified using the Java configuration property syntax in any and all .properties files:

cas.jdbc.physical-table-names=...

CAS properties can be specified using the YAML syntax:

cas: 
  jdbc: 
    physical-table-names: "..."

Note that YAML is very specific about structure and indentation. Be sure to verify the correctness of the final result with your YAML validator of choice.

CAS properties can be passed to the CAS web application as system properties, when the application is launched:

java -Dcas.jdbc.physical-table-names="..." -jar build/libs/cas.war

CAS properties can specified as system environment variables before the CAS web application is launched:

export CAS_JDBC_PHYSICAL_TABLE_NAMES="..."

java -jar build/libs/cas.war

The above example assumes that the CAS web application is packaged as cas.war with an embedded server container and can be found in the build/libs directory.

CAS properties can be passed to the CAS web application as command-line arguments, when the application is launched:

java -jar build/libs/cas.war --cas.jdbc.physical-table-names="..."

The above example assumes that the CAS web application is packaged as cas.war with an embedded server container and can be found in the build/libs directory.

cas.jdbc.show-sql=false

Whether SQL queries should be displayed in the console/logs.

_{How can I configure this property?}

Configuration properties can be included and activated using the following strategies.

Note

CAS properties can be specified using the Java configuration property syntax in any and all .properties files:

cas.jdbc.show-sql=...

CAS properties can be specified using the YAML syntax:

cas: 
  jdbc: 
    show-sql: "..."

Note that YAML is very specific about structure and indentation. Be sure to verify the correctness of the final result with your YAML validator of choice.

CAS properties can be passed to the CAS web application as system properties, when the application is launched:

java -Dcas.jdbc.show-sql="..." -jar build/libs/cas.war

CAS properties can specified as system environment variables before the CAS web application is launched:

export CAS_JDBC_SHOW_SQL="..."

java -jar build/libs/cas.war

The above example assumes that the CAS web application is packaged as cas.war with an embedded server container and can be found in the build/libs directory.

CAS properties can be passed to the CAS web application as command-line arguments, when the application is launched:

java -jar build/libs/cas.war --cas.jdbc.show-sql="..."

The above example assumes that the CAS web application is packaged as cas.war with an embedded server container and can be found in the build/libs directory.

H2

Available drivers are:

org.h2.Driver

Dialects
`org.hibernate.dialect.H2Dialect`

HSQLDB

Available drivers are:

org.hsqldb.jdbcDriver

Dialects
`org.hibernate.dialect.HSQLDialect`

Oracle

Available drivers are:

oracle.jdbc.driver.OracleDriver

Dialects
`org.hibernate.dialect.OracleDialect`

MYSQL

Available drivers are:

com.mysql.jdbc.Driver
com.mysql.cj.jdbc.Driver

Dialects
`org.hibernate.dialect.MySQLDialect`

PostgreSQL

Available drivers are:

org.postgresql.Driver

Dialects
`org.hibernate.dialect.PostgreSQLDialect`

MariaDB

Available drivers are:

org.mariadb.jdbc.Driver

Dialects
`org.hibernate.dialect.MariaDBDialect`

Microsoft SQL Server

Available drivers are:

net.sourceforge.jtds.jdbc.Driver
com.microsoft.sqlserver.jdbc.SQLServerDriver

Dialects
`org.hibernate.dialect.SQLServerDialect`