Server-side Sessions - JDBC
If you don’t wish to use the native container’s strategy for session replication, you can use CAS’s support for JDBC session replication.
This feature is enabled via the following module:
1
2
3
4
5
<dependency>
<groupId>org.apereo.cas</groupId>
<artifactId>cas-server-support-session-jdbc</artifactId>
<version>${cas.version}</version>
</dependency>
1
implementation "org.apereo.cas:cas-server-support-session-jdbc:${project.'cas.version'}"
1
2
3
4
5
6
7
8
9
dependencyManagement {
imports {
mavenBom "org.apereo.cas:cas-server-support-bom:${project.'cas.version'}"
}
}
dependencies {
implementation "org.apereo.cas:cas-server-support-session-jdbc"
}
1
2
3
4
5
6
7
8
9
10
dependencies {
/*
The following platform references are included automatically and are listed 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-session-jdbc"
}
The following settings and properties are available from the CAS configuration catalog:
spring.datasource.azure.credential.client-certificate-passwordPassword of the certificate file.
Password of the certificate file.
spring.datasource.azure.credential.client-certificate-pathPath of a PEM certificate file to use when performing service principal authentication with Azure.
Path of a PEM certificate file to use when performing service principal authentication with Azure.
spring.datasource.azure.credential.client-idClient ID to use when performing service principal authentication with Azure.
Client ID to use when performing service principal authentication with Azure.
spring.datasource.azure.credential.client-secretClient secret to use when performing service principal authentication with Azure.
Client secret to use when performing service principal authentication with Azure.
spring.datasource.azure.credential.managed-identity-enabledWhether to enable managed identity to authenticate with Azure.
falseWhether to enable managed identity to authenticate with Azure. If true and the client-id is set, will use the client ID as user assigned managed identity client ID.
spring.datasource.azure.credential.passwordPassword to use when performing username/password authentication with Azure.
Password to use when performing username/password authentication with Azure.
spring.datasource.azure.credential.usernameUsername to use when performing username/password authentication with Azure.
Username to use when performing username/password authentication with Azure.
spring.datasource.azure.passwordless-enabledWhether to enable passwordless connections to Azure databases by using OAuth2 Microsoft Entra token credentials.
falseWhether to enable passwordless connections to Azure databases by using OAuth2 Microsoft Entra token credentials.
spring.datasource.azure.profile.cloud-typeName of the Azure cloud to connect to.
Name of the Azure cloud to connect to. Supported types are: AZURE, AZURE_CHINA, AZURE_US_GOVERNMENT, OTHER. The default value is `AZURE`.
spring.datasource.azure.profile.environment.active-directory-endpointThe Microsoft Entra endpoint to connect to.
The Microsoft Entra endpoint to connect to.
spring.datasource.azure.profile.tenant-idTenant ID for Azure resources.
Tenant ID for Azure resources. The values allowed for 'tenant-id' are: 'common', 'organizations', 'consumers', or the tenant ID.
spring.datasource.connection-fetchWhether the auto-configured DataSource should be wrapped in a proxy that fetches JDBC connections as late as possible.
eagerWhether the auto-configured DataSource should be wrapped in a proxy that fetches JDBC connections as late as possible.
spring.datasource.continue-on-error
spring.datasource.data
spring.datasource.data-password
spring.datasource.data-username
spring.datasource.dbcp2.abandoned-usage-tracking
spring.datasource.dbcp2.access-to-underlying-connection-allowed
spring.datasource.dbcp2.auto-commit-on-return
spring.datasource.dbcp2.cache-state
spring.datasource.dbcp2.clear-statement-pool-on-return
spring.datasource.dbcp2.connection-factory-class-name
spring.datasource.dbcp2.connection-init-sqls
spring.datasource.dbcp2.default-auto-commit
spring.datasource.dbcp2.default-catalog
spring.datasource.dbcp2.default-query-timeout
spring.datasource.dbcp2.default-read-only
spring.datasource.dbcp2.default-schema
spring.datasource.dbcp2.default-transaction-isolation
spring.datasource.dbcp2.disconnection-ignore-sql-codes
spring.datasource.dbcp2.disconnection-sql-codes
spring.datasource.dbcp2.driver-class-name
spring.datasource.dbcp2.duration-between-eviction-runs
spring.datasource.dbcp2.enable-auto-commit-on-return
spring.datasource.dbcp2.eviction-policy-class-name
spring.datasource.dbcp2.fast-fail-validation
spring.datasource.dbcp2.initial-size
spring.datasource.dbcp2.jmx-name
spring.datasource.dbcp2.lifo
spring.datasource.dbcp2.log-abandoned
spring.datasource.dbcp2.log-expired-connections
spring.datasource.dbcp2.login-timeout
spring.datasource.dbcp2.max-conn-lifetime-millis
spring.datasource.dbcp2.max-idle
spring.datasource.dbcp2.max-open-prepared-statements
spring.datasource.dbcp2.max-total
spring.datasource.dbcp2.max-wait-millis
spring.datasource.dbcp2.min-evictable-idle-time-millis
spring.datasource.dbcp2.min-idle
spring.datasource.dbcp2.num-tests-per-eviction-run
spring.datasource.dbcp2.password
spring.datasource.dbcp2.pool-prepared-statements
spring.datasource.dbcp2.remove-abandoned-on-borrow
spring.datasource.dbcp2.remove-abandoned-on-maintenance
spring.datasource.dbcp2.remove-abandoned-timeout
spring.datasource.dbcp2.rollback-on-return
spring.datasource.dbcp2.soft-min-evictable-idle-time-millis
spring.datasource.dbcp2.test-on-borrow
spring.datasource.dbcp2.test-on-create
spring.datasource.dbcp2.test-on-return
spring.datasource.dbcp2.test-while-idle
spring.datasource.dbcp2.time-between-eviction-runs-millis
spring.datasource.dbcp2.url
spring.datasource.dbcp2.username
spring.datasource.dbcp2.validation-query
spring.datasource.dbcp2.validation-query-timeout
spring.datasource.driver-class-nameFully qualified name of the JDBC driver.
Fully qualified name of the JDBC driver. Auto-detected based on the URL by default.
spring.datasource.embedded-database-connectionConnection details for an embedded database.
Connection details for an embedded database. Defaults to the most suitable embedded database that is available on the classpath.
spring.datasource.generate-unique-nameWhether to generate a random datasource name.
trueWhether to generate a random datasource name.
spring.datasource.hikari.allow-pool-suspension
spring.datasource.hikari.auto-commit
spring.datasource.hikari.catalog
spring.datasource.hikari.connection-init-sql
spring.datasource.hikari.connection-test-query
spring.datasource.hikari.connection-timeout
spring.datasource.hikari.credentials-provider-class-name
spring.datasource.hikari.data-source-class-name
spring.datasource.hikari.data-source-j-n-d-i
spring.datasource.hikari.data-source-properties
spring.datasource.hikari.driver-class-name
spring.datasource.hikari.exception-override-class-name
spring.datasource.hikari.health-check-properties
spring.datasource.hikari.idle-timeout
spring.datasource.hikari.initialization-fail-timeout
spring.datasource.hikari.isolate-internal-queries
spring.datasource.hikari.jdbc-url
spring.datasource.hikari.keepalive-time
spring.datasource.hikari.leak-detection-threshold
spring.datasource.hikari.login-timeout
spring.datasource.hikari.max-lifetime
spring.datasource.hikari.maximum-pool-size
spring.datasource.hikari.minimum-idle
spring.datasource.hikari.password
spring.datasource.hikari.pool-name
spring.datasource.hikari.read-only
spring.datasource.hikari.register-mbeans
spring.datasource.hikari.schema
spring.datasource.hikari.transaction-isolation
spring.datasource.hikari.username
spring.datasource.hikari.validation-timeout
spring.datasource.initialization-mode
spring.datasource.jmx-enabledWhether to enable JMX support (if provided by the underlying pool).
falseWhether to enable JMX support (if provided by the underlying pool).
spring.datasource.jndi-nameJNDI location of the datasource.
JNDI location of the datasource. Class, url, username and password are ignored when set.
spring.datasource.nameDatasource name to use if "generate-unique-name" is false.
Datasource name to use if "generate-unique-name" is false. Defaults to "testdb" when using an embedded database, otherwise null.
spring.datasource.oracleucp.abandoned-connection-timeout
spring.datasource.oracleucp.commit-on-connection-return
spring.datasource.oracleucp.connection-affinity-callback
spring.datasource.oracleucp.connection-creation-consumer
spring.datasource.oracleucp.connection-factory-class-name
spring.datasource.oracleucp.connection-factory-properties
spring.datasource.oracleucp.connection-harvest-max-count
spring.datasource.oracleucp.connection-harvest-trigger-count
spring.datasource.oracleucp.connection-initialization-callback
spring.datasource.oracleucp.connection-labeling-callback
spring.datasource.oracleucp.connection-labeling-high-cost
spring.datasource.oracleucp.connection-pool-name
spring.datasource.oracleucp.connection-properties
spring.datasource.oracleucp.connection-repurpose-threshold
spring.datasource.oracleucp.connection-validation-timeout
spring.datasource.oracleucp.connection-wait-duration
spring.datasource.oracleucp.connection-wait-timeout
spring.datasource.oracleucp.connection-wait-timeout-while-service-down
spring.datasource.oracleucp.create-connection-in-borrow-thread
spring.datasource.oracleucp.data-source-name
spring.datasource.oracleucp.database-name
spring.datasource.oracleucp.description
spring.datasource.oracleucp.fast-connection-failover-enabled
spring.datasource.oracleucp.high-cost-connection-reuse-threshold
spring.datasource.oracleucp.inactive-connection-timeout
spring.datasource.oracleucp.initial-pool-size
spring.datasource.oracleucp.login-timeout
spring.datasource.oracleucp.max-connection-reuse-count
spring.datasource.oracleucp.max-connection-reuse-time
spring.datasource.oracleucp.max-connections-per-shard
spring.datasource.oracleucp.max-idle
spring.datasource.oracleucp.max-idle-time
spring.datasource.oracleucp.max-pool-size
spring.datasource.oracleucp.max-statements
spring.datasource.oracleucp.min-idle
spring.datasource.oracleucp.min-pool-size
spring.datasource.oracleucp.network-protocol
spring.datasource.oracleucp.o-n-s-configuration
spring.datasource.oracleucp.password
spring.datasource.oracleucp.pdb-roles
spring.datasource.oracleucp.port-number
spring.datasource.oracleucp.property-cycle
spring.datasource.oracleucp.query-timeout
spring.datasource.oracleucp.read-only-instance-allowed
spring.datasource.oracleucp.s-q-l-for-validate-connection
spring.datasource.oracleucp.seconds-to-trust-idle-connection
spring.datasource.oracleucp.server-name
spring.datasource.oracleucp.sharding-mode
spring.datasource.oracleucp.time-to-live-connection-timeout
spring.datasource.oracleucp.timeout-check-interval
spring.datasource.oracleucp.u-r-l
spring.datasource.oracleucp.user
spring.datasource.oracleucp.validate-connection-on-borrow
spring.datasource.passwordLogin password of the database.
Login password of the database.
spring.datasource.platform
spring.datasource.schema
spring.datasource.schema-password
spring.datasource.schema-username
spring.datasource.separator
spring.datasource.sql-script-encoding
spring.datasource.tomcat.abandon-when-percentage-full
spring.datasource.tomcat.access-to-underlying-connection-allowed
spring.datasource.tomcat.alternate-username-allowed
spring.datasource.tomcat.commit-on-return
spring.datasource.tomcat.connection-properties
spring.datasource.tomcat.data-source-j-n-d-i
spring.datasource.tomcat.db-properties
spring.datasource.tomcat.default-auto-commit
spring.datasource.tomcat.default-catalog
spring.datasource.tomcat.default-read-only
spring.datasource.tomcat.default-transaction-isolation
spring.datasource.tomcat.driver-class-name
spring.datasource.tomcat.fair-queue
spring.datasource.tomcat.ignore-exception-on-pre-load
spring.datasource.tomcat.init-s-q-l
spring.datasource.tomcat.initial-size
spring.datasource.tomcat.jdbc-interceptors
spring.datasource.tomcat.jmx-enabled
spring.datasource.tomcat.log-abandoned
spring.datasource.tomcat.log-validation-errors
spring.datasource.tomcat.login-timeout
spring.datasource.tomcat.max-active
spring.datasource.tomcat.max-age
spring.datasource.tomcat.max-idle
spring.datasource.tomcat.max-wait
spring.datasource.tomcat.min-evictable-idle-time-millis
spring.datasource.tomcat.min-idle
spring.datasource.tomcat.name
spring.datasource.tomcat.num-tests-per-eviction-run
spring.datasource.tomcat.password
spring.datasource.tomcat.propagate-interrupt-state
spring.datasource.tomcat.remove-abandoned
spring.datasource.tomcat.remove-abandoned-timeout
spring.datasource.tomcat.rollback-on-return
spring.datasource.tomcat.suspect-timeout
spring.datasource.tomcat.test-on-borrow
spring.datasource.tomcat.test-on-connect
spring.datasource.tomcat.test-on-return
spring.datasource.tomcat.test-while-idle
spring.datasource.tomcat.time-between-eviction-runs-millis
spring.datasource.tomcat.url
spring.datasource.tomcat.use-disposable-connection-facade
spring.datasource.tomcat.use-equals
spring.datasource.tomcat.use-lock
spring.datasource.tomcat.use-statement-facade
spring.datasource.tomcat.username
spring.datasource.tomcat.validation-interval
spring.datasource.tomcat.validation-query
spring.datasource.tomcat.validation-query-timeout
spring.datasource.tomcat.validator-class-name
spring.datasource.typeFully qualified name of the DataSource implementation to use.
Fully qualified name of the DataSource implementation to use. By default, a connection pool implementation is auto-detected from the classpath.
spring.datasource.urlJDBC URL of the database.
JDBC URL of the database.
spring.datasource.usernameLogin username of the database.
Login username of the database.
spring.datasource.xa.data-source-class-nameXA datasource fully qualified name.
XA datasource fully qualified name.
spring.datasource.xa.propertiesProperties to pass to the XA data source.
Properties to pass to the XA data source.
spring.session.jdbc.cleanup-cronCron expression for expired session cleanup job.
0 * * * * *Cron expression for expired session cleanup job.
spring.session.jdbc.continue-on-errorWhether initialization should continue when an error occurs when applying a schema script.
trueWhether initialization should continue when an error occurs when applying a schema script.
spring.session.jdbc.flush-modeSessions flush mode.
on-saveSessions flush mode. Determines when session changes are written to the session store.
spring.session.jdbc.initialize-schemaDatabase schema initialization mode.
embeddedDatabase schema initialization mode.
spring.session.jdbc.platformPlatform to use in initialization scripts if the @@platform@@ placeholder is used.
Platform to use in initialization scripts if the @@platform@@ placeholder is used. Auto-detected by default.
spring.session.jdbc.save-modeSessions save mode.
on-set-attributeSessions save mode. Determines how session changes are tracked and saved to the session store.
spring.session.jdbc.schemaPath to the SQL file to use to initialize the database schema.
Path to the SQL file to use to initialize the database schema.
spring.session.jdbc.table-nameName of the database table used to store sessions.
SPRING_SESSIONName of the database table used to store sessions.
Required settings may be needed to activate or affect the feature; review them even when they have a default. Optional settings only need to be set to change a default or to turn on the behavior they control. Third party settings belong to libraries such as Spring Boot that CAS builds on; their own documentation may have more detail.
Hibernate & JDBC
Control global properties that are relevant to Hibernate, when CAS attempts to employ and utilize database resources, connections and queries.
cas.jdbc.gen-ddlWhether to generate DDL after the EntityManagerFactory has been initialized creating/updating all relevant tables.
trueWhether to generate DDL after the EntityManagerFactory has been initialized creating/updating all relevant tables.
cas.jdbc.physical-table-namesIndicate 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.
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-sqlWhether SQL queries should be displayed in the console/logs.
falseWhether SQL queries should be displayed in the console/logs.
Groovy scripting
CAS takes advantage of Apache Groovy in forms of either embedded or external scripts that allow one to, by default, dynamically build constructs, attributes, access strategies and a lot more. To activate the functionality described here, you may need to prepare CAS to support and integrate with Apache Groovy.
Please review this guide to configure your build.
Notes on configuration
Configuration Metadata
The collection of configuration properties listed in this section are automatically generated from the CAS source and components that contain the actual field definitions, types, descriptions, modules, etc. This metadata may not always be 100% accurate, or could be lacking details and sufficient explanations.
Be Selective
This section is meant as a guide only. Do NOT copy/paste the entire collection of settings into your CAS configuration; rather pick only the properties that you need. Do NOT enable settings unless you are certain of their purpose and do NOT copy settings into your configuration only to keep them as reference. All these ideas lead to upgrade headaches, maintenance nightmares and premature aging.
YAGNI
Note that for nearly ALL use cases, declaring and configuring properties listed here is sufficient. You should NOT have to explicitly massage a CAS XML/Java/etc configuration file to design an authentication handler, create attribute release policies, etc. CAS at runtime will auto-configure all required changes for you. If you are unsure about the meaning of a given CAS setting, do NOT turn it on without hesitation. Review the codebase or better yet, ask questions to clarify the intended behavior.
Naming Convention
Property names can be specified in very relaxed terms. For instance cas.someProperty, cas.some-property, cas.some_property are all valid names. While all
forms are accepted by CAS, there are certain components (in CAS and other frameworks used) whose activation at runtime is conditional on a property value, where
this property is required to have been specified in CAS configuration using kebab case. This is both true for properties that are owned by CAS as well as those
that might be presented to the system via an external library or framework such as Spring Boot, etc.
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.
Settings and properties that are controlled by the CAS platform directly always begin with the prefix cas. All other settings are controlled and provided
to CAS via other underlying frameworks and may have their own schemas and syntax. BE CAREFUL with
the distinction. Unrecognized properties are rejected by CAS and/or frameworks upon which CAS depends. This means if you somehow misspell a property definition
or fail to adhere to the dot-notation syntax and such, your setting is entirely refused by CAS and likely the feature it controls will never be activated in the
way you intend.
Validation
Configuration properties are automatically validated on CAS startup to report issues with configuration binding, especially if defined CAS settings cannot be recognized or validated by the configuration schema. Additional validation processes are also handled via Configuration Metadata and property migrations applied automatically on startup by Spring Boot and family.
Indexed Settings
CAS settings able to accept multiple values are typically documented with an index, such as cas.some.setting[0]=value. The index [0] is meant to be
incremented by the adopter to allow for distinct multiple configuration blocks.