Product Knowledge Base

Space shortcuts

Page tree

Versions Compared

Old Version 12

changes.mady.by.user Kanika Agrawal

Saved on

compared with

New Version Current

changes.mady.by.user Andreas Püschel

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Table of Contents

Introduction

The Hibernate configuration files are the Database configuration files. The database information like database users, passwords, and jdbc URLs etc are specified in the hibernate configuration files. These files configuration 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 or of JOC Cockpit and JobScheduler Master and they can be created later on for the using with the ManagedDatabaseJobJSAdapterClass job.The Hibernate configuration files used by installation are: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:
        JobScheduler run
        • Run-time database: hibernate.cfg.xml
        for JobScheduler and jobscheduler
        • Reporting database: reporting.hibernate.cfg.xml 
      • for JOC Cockpit:
        • JobScheduler run-time database: jobscheduler.hibernate.cfg.xml

        • Reporting database: reporting.hibernate.cfg.xml 

    • Database accounts, passwords, and URLs are specified as plain text with the above hibernate 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 to use the database information from the access data from a Credential Store it is required to first create the hibernate configuration files file and then to use the <entry key="databaseConfigurationMethod" value="withHibernateFile"/> at the time of installation and to provide the path to the Hibernate configurations file.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 filesHibernate configuration file also supports Credential Store. 
      Display feature availability
      StartingFromRelease1.13.3

      Display feature availability
      StartingFromRelease1.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: 

    Full Syntax

    The Full syntax is used when the complete URI is to specified with each property element of the Hibernate configuration file

    URI

    cs://<entry_path>@<property_name> - required 

    • The URI based syntax includes the protocol cs:// 
    • followed by the <entry_path> that specifies the directory structure and entry name in the credentials store file.
    • 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,attachment Custom field names are supported. 

    Query Parameters

    • file - required 
      the path to the credential store database file. This file can be stored anywhere in the file system.

    • password - optional 
      the password for the credential store database 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_database_filename_without_extension>.key 

    For detailed information about query parameter Query Parameters.

    Syntax:

    The Full syntax used in the hibernate file to access the credentials: 

    • <property name="hibernate.connection.passwordusername">cs://<entry_path>@usersecret/database/reporting@user?file=some/path/database.kdbx<./config/live/hibernate_example/secret.kdbx</property> 
    • <property name="hibernate.connection.password">cs>cs://secret/database/<entry_path>@passwordreporting@password?file=some/path/database.kdbx<./config/live/hibernate_example/secret.kdbx</property>

    • <property name="hibernate.connection.url">cs>cs://secret/database/<entry_path>reporting@url?file=some/path/database.kdbx<./config/live/hibernate_example/secret.kdbx</property>

    Alternatively, use the short syntax in the hibetnate file : 

    • <property name="hibernate.connection.username">cs://@user</property> 
    • <property name="hibernate.connection.password">cs://@password</property> 
    • <property name="hibernate.connection.url">cs://@url</property>

    Explanations:

    • The secret/database/reporting value is an example for a path to an entry in the KeePass database that holds the credentials.
    • The ./config/live/hibernate_example/secret.kdbx value is an example for a relative path to the KeePass database that holds the Credential Store.

    Short Syntax

    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       Inroducing new hibernate configuration credential store items for the Short syntax:

    • <property name="hibernate.sos.credential_store_file">some/path/database.kdbx</property> >./config/live/hibernate_example/secret.kdbx</property> → stores the path to the Credential Store file
    • <property name="hibernate.sos.credential_store_key_file">some/path/database.key</property> >./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">some password<>secret</property>  → stores the password of the Credential Store file
    • <property name="hibernate.sos.credential_store_entry_path">/somesecret/entrydatabase/path<reporting</property> 

    Save the custom hibernate.cfg.xml file on any location and assign the path of the hibernate file in the job parameter. 

    Example of hibernate file that uses KeePass for access database credential

    ...

    languagexml
    titleExample
    collapsetrue
    •  → 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: 

    • <property

    ...

    • name="hibernate.connection.

    ...

    • username">cs://@user</property> 
    • <property name="hibernate.connection.

    ...

    • password">cs://@password</property> 
    • <property name="hibernate.connection.

    ...

    • url">cs://

    ...

    • @url</property> 

    URI and Query Parameters Hibernate Configuration Files

    URI

    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. 

    Query Parameters

    • 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.

    Example

    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):

    Explanations

    • Hibernate file make use of kdbx KeePass database for accessing Database credential
    • <entry_path> of the kdbx database of KeePass Credential Store
    • file-File path of kdbx keePass database.
    • password- Password for accessing kdbx database where credentials store

    Example of hibernate file with a key file for the credential store database file.  

    Code Block
    languagexml
    titleExample
    collapsetrue
    <?xml version="1.0" encoding="UTF-8" standalone="no"?> 
<hibernate-configuration> 
  <session-factory> 
<property namefactory>
    <property name="hibernate.connection.url"><![CDATA[cs://secret/kdbx-p-f/MySQL@urldatabase/reporting@url?file=./config/live/keepass/kdbx-p-fhibernate_example/secret.kdbx]]></property> 
<property nameproperty>
    <property name="hibernate.connection.username"><![CDATA[cs://secret/kdbx-p-f/MySQL@usernamedatabase/reporting@user?file=./config/live/keepass/kdbx-p-fhibernate_example/secret.kdbx]]></property> 
<property nameproperty>
    <property name="hibernate.connection.password"><![CDATA[cs://secret/kdbx-p-f/MySQL@passworddatabase/reporting@password?file=./config/live/keepass/kdbx-p-fhibernate_example/secret.kdbx]]></property> property>
    <property name="hibernate.connection.driver_class">org.mariadb.jdbc.Driver</property> 
    <property name="hibernate.dialect">org.hibernate.dialect.MySQLInnoDBDialect</property> 
    <property name="hibernate.show_sql">false</property> 
    <property name="hibernate.connection.autocommit">false</property>  
    <property name="hibernate.format_sql">true</property> 
    <property name="hibernate.temp.use_jdbc_metadata_defaults">false</property> 
  </session-factory> 
</hibernate-configuration> 


    Explanations

    • The Hibernate file make makes use of the KeePass database secret.kdbx located in the ./config/live/hibernate_example folder of JobScheduler Master with Key File Authentication for accessing Database credential
    • <entry_path> path where the MySQL database credential stores.
    • file- is the file path where the kdbx key file stores.

    Downloads

    ...

    • .
    • cs://secret/database/reporting is the path to the entry in the KeePass database where the database credentials are stored.

    Notes:

    • 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

    Using the Example

    • Unzip the archive to the ./config/live folder of JobScheduler installation Master. This will create a sub-folder hibernate_example.
    • Add the database configuration according to your environment in the KDBX database (present in the example folder)  for using the kdbx with the key file which accesses the credential to log in to the databaseto the KeePass database secret.kdbx.. Access to the KeePass database is secured with the key file secret.key.
    • Make the changes for database access (URL, username, password).
    • The hibernate-cs.syntax.full.cfg.xml file includes the elements to access the KeePass database.
    • The query_database job includes the database query to be executed: select count(*) as number_of_hits from SCHEDULER_HISTORY;
    • The display_results job echos the value of the result parameter number_of_hits to the log..
    • Run the order hibernate_order from JOC Cockpit.
    • The output of the database query will be displayed with the log.

    References

    • Links to Change Management System 
      • Jira
        serverSOS JIRA
        columnskey,summary,type,created,updated,due,assignee,reporter,priority,status,resolution
        serverId6dc67751-9d67-34cd-985b-194a8cdc9602
        keyJITL-587
      • Jira
        serverSOS JIRA
        columnskey,summary,type,created,updated,due,assignee,reporter,priority,status,resolution
        serverId6dc67751-9d67-34cd-985b-194a8cdc9602
        keyJITL-589