The Hibernate access layer is used for database access and therefore requires configuration files for credentials. The access information such as accounts, passwords and JDBC URLs etc. are specified in Hibernate configuration files. Such files can be used at the time of installation of JOC Cockpit and JobScheduler Master and they can be created later on for individual jobs, e.g. the for use with the Job JobSchedulerManagedDatabaseJobSOSHibernate.
Generally it is preferable not to use passwords to access a database but to use Integrated Security, Oracle Wallet etc. However, should there be a need to specify passwords then instead of using a plain text password in a configuration file you can add your password to a KeePass Credential Store and add a reference for the Credential Store to your Hibernate configuration file.
- The following hibernate configuration files are available with JobScheduler Master and JOC Cockpit:
- JobScheduler Master:
- Run-time database: hibernate.cfg.xml
- Reporting database: reporting.hibernate.cfg.xml
- JOC Cockpit:
- JobScheduler run-time database: jobscheduler.hibernate.cfg.xml
Reporting database: reporting.hibernate.cfg.xml
- JobScheduler Master:
- Database accounts, passwords, and URLs are specified as plain text with the above Hibernate configuration files when they are provided at the time of installation using the option
<entry key="databaseConfigurationMethod" value="withoutHibernateFile"/>. To make the hibernate configuration file use access data from a Credential Store it is required to first create the hibernate configuration file and then to use the
<entry key="databaseConfigurationMethod" value="withHibernateFile"/>at the time of installation and to provide the path to the Hibernate configuration file e.g. with a value like this:
<entry key="reporting.hibernateConfFile" value="jobscheduler.hibernate.cfg.xml"/>.
- Support for use of a Credential Store with Hibernate configuration files
FEATURE AVAILABILITY STARTING FROM RELEASE 1.13.3
FEATURE AVAILABILITY STARTING FROM RELEASE 1.12.12
Referencing a Credential Store
Syntax for Hibernate Configuration Files
The Hibernate configuration file is introduced with different elements (properties) that can be used to retrieve the information from a Credential Store. It provides two types of syntax:
The Full syntax is used when the complete URI is to specified with each property element of the Hibernate configuration file:
secret/database/reportingvalue is an example for a path to an entry in the KeePass database that holds the credentials.
./config/live/hibernate_example/secret.kdbxvalue is an example for a relative path to the KeePass database that holds the Credential Store.
The Short syntax is used when the credential store items are to be used in the hibernate configuration to provide the details about the credential store:
<property name="hibernate.sos.credential_store_file">./config/live/hibernate_example/secret.kdbx</property>→ stores the path to the Credential Store file
<property name="hibernate.sos.credential_store_key_file">./config/live/hibernate_example/secret.key</property>→ stores the path of the key file for the Credential Store
<property name="hibernate.sos.credential_store_password">secret</property>→ stores the password of the Credential Store file
<property name="hibernate.sos.credential_store_entry_path">/secret/database/reporting</property>→ specifies the folder hierarchy and entry name in the Credentials Store file
After adding the Credential Store reference to the Hibernate configuration file as above the credentials can be retrieved from the Credential Store by using the following property elements:
URI and Query Parameters Hibernate Configuration Files
cs://<entry_path>@<property_name> - required
- The URI based syntax includes the protocol cs://
- followed by the <entry_path> that specifies the folder hierarchy and entry name in the Credentials Store.
- followed by the @ character
followed by the <property_name> that should be retrieved:
- frequently-used properties include Credential Store field names such as title, user, password, url, attachment. Custom field names are supported.
file - required
the path to the Credential Store file. This file can be located anywhere in the file system.
password - optional
the password for the Credential Store file.
It is recommended not to use this parameter and instead to use a key_file to access the Credential Store.
key_file - optional, default: <credential_store_filename_without_extension>.key
Refer to the Using a Credential Store for Jobs article for a detailed description.
Hibernate Configuration File
Example of a Hibernate configuration file for MySQL that makes use of a KeePass database that is secured with a key file (same name as the KeePass database but with extension .key):
- The Hibernate file makes use of the KeePass database
secret.kdbxlocated in the
./config/live/hibernate_examplefolder of JobScheduler Master with Key File Authentication.
cs://secret/database/reportingis the path to the entry in the KeePass database where the database credentials are stored.
- If the base names of the KeePass database (
secret.kdbx) and of the key file (
secret.key) are the same and if the files are stored in the same location then it is not required to specify the key file as it will be automatically looked up.
- It is possible to secure a KeePass database with a password, however, this makes no sense in a context that avoids directly readable passwords. A key file can better be secured by OS permissions that rule access to the key file.
- Download the attached archive hibernate_example.zip
Using the Example
- Unzip the archive to the
./config/livefolder of JobScheduler Master. This will create a sub-folder
- Add the database configuration according to your environment to the KeePass database
secret.kdbx.. Access to the KeePass database is secured with the key file
- Make the changes for database access (URL, username, password).
hibernate-cs.syntax.full.cfg.xmlfile includes the elements to access the KeePass database.
query_databasejob includes the database query to be executed:
select count(*) as number_of_hits from SCHEDULER_HISTORY;
display_resultsjob echos the value of the result parameter
number_of_hitsto the log..
- Run the order hibernate_order from JOC Cockpit.
- The output of the database query will be displayed with the log.
- Links to Change Management System