Skip to end of metadata
Go to start of metadata

Introduction

A number of JS7 - Job Templates support use of a Credential Store:

A number of JITL Job Templates require credentials, e.g. to access a database.

  • Security Considerations
    • Sensitive information in jobs should not be hard-coded, should not be used from parameters and should not be disclosed, e.g. written to log files.
    • Instead, a run-time interface is offered that allows to retrieve sensitive information from a Credential Store. References to Credential Store entries can safely be specified with argument values.
  • Credential Store
  • Solution Outline

Credential Store Access

Access to a Credential Store is specified with the URI and Query Parameters of the Credential Store.

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, userpassword, urlattachmentCustom 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.
    • A relative path can be used that is calculated from the Agent's working directory:
      • By default this is the Agent's configuration directory, for example
        • /home/sos/js7/agent/var_<http-port> for Unix
        • C:\ProgramData\sos-berlin.com\js7\agent for Windows
      • Example
        • a relative path ./config/secret.kdbx maps to C:\ProgramData\sos-berlin.com\js7\agent\config\secret.kdbx
  • password - optional 

    • the password for access to 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: the path and name of the Credential Store file using the extension .key, for example, by default ./config/jobs.key is assumed if the Credential Store file ./config/jobs.kdbx is specified.

Use with JITL Database Jobs

JITL Database Jobs can access a Credential Store in the following ways:

  • by use of a Hibernate configuration file,
  • by use of arguments

Use with a Hibernate Configuration File

The Hibernate access layer is used for database access and frequently requires database credentials. The access information such as accounts, passwords and JDBC URLs etc. are specified with Hibernate configuration files. 

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. This applies to the following JITL Database Jobs:

References to a Credential Store

The Hibernate configuration file includes a number of XML elements that can be populated from a Credential Store. It provides two types of syntax.

Full Syntax

The full syntax is used when the complete URI is specified with each element of the Hibernate configuration file: 

Extract from Hibernate configuration file with credential store references using the full syntax
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<hibernate-configuration>
    <session-factory>
        ...
        <property name="hibernate.connection.username">cs://secret/database/reporting@user?file=./config/secret.kdbx</property> 
        <property name="hibernate.connection.password">cs://secret/database/reporting@password?file=./config/secret.kdbx</property>
        <property name="hibernate.connection.url">cs://secret/database/reporting@url?file=./config/secret.kdbx</property>
        ...
    </session-factory>
</hibernate-configuration

Explanation:

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

Short Syntax

The short syntax can be used if the Hibernate configuration file includes explicit references to the Credential Store:

Extract from Hibernate configuration file with credential store references using the short syntax
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<hibernate-configuration>
    <session-factory>
        ...
        <property name="hibernate.connection.username">cs://@user</property> 
        <property name="hibernate.connection.password">cs://@password</property> 
        <property name="hibernate.connection.url">cs://@url</property>
         ...
        <property name="hibernate.sos.credential_store_file">./config/secret.kdbx</property>
        <property name="hibernate.sos.credential_store_key_file">./config/secret.key</property>
        <property name="hibernate.sos.credential_store_password">secret</property>
        <property name="hibernate.sos.credential_store_entry_path">/secret/database/reporting</property>
        ...
    </session-factory>
</hibernate-configuration

Explanation:

  • <property name="hibernate.sos.credential_store_file"> => path to the Credential Store database file
  • <property name="hibernate.sos.credential_store_key_file"> => path to the key file for the Credential Store
  • <property name="hibernate.sos.credential_store_password"> => password of the Credential Store database file
  • <property name="hibernate.sos.credential_store_entry_path"> => folder hierarchy and entry name in the Credentials Store database file

Example for Hibernate Configuration File

A Hibernate configuration file using a reference to the Credential Store and the short syntax for credential references can look like this:

Example Hibernate configuration file for MySQL
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<hibernate-configuration>
 <session-factory>
  <property name="hibernate.sos.credential_store_file">./config/jobs.kdbx</property>
  <property name="hibernate.sos.credential_store_key">./config/private/jobs.key</property>
  <property name="hibernate.connection.driver_class">org.mariadb.jdbc.Driver</property>
  <property name="hibernate.connection.password">cs://jobs/mysql/mysql-5-7@password</property>
  <property name="hibernate.connection.url">cs://jobs/mysql/mysql-5-7@url</property>
  <property name="hibernate.connection.username">cs://jobs/mysql/mysql-5-7@user</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>

  <!-- Hikari Connection Pool -->
  <property name="hibernate.connection.provider_class">org.hibernate.hikaricp.internal.HikariCPConnectionProvider</property>
  <property name="hibernate.hikari.maximumPoolSize">10</property>
 </session-factory>
</hibernate-configuration>


Explanation:

  • <property name="hibernate.sos.credential_store_file"> specifies the location of the Credential Store database file.
  • <property name="hibernate.sos.credential_store_key"> specifies the location of the Credential Store key file. In this example the key file is stored with a location different to the database file and therefore has to be specified. If the key file is available from the same folder as the database file and makes use of the same base name then this parameter can be omitted.

Use with Arguments

References to a Credential Store can be directly specified from arguments. This applies to the following JITL Database Jobs:

References to a Credential Store

References to a credential store can be directly specified from arguments.

Full Syntax

The full syntax is used when the complete URI is specified with an argument: 

Name

Purpose

Example

db_url

JDBC connection string

cs://jobs/oracle/minos.sos@url?file=./config/jobs.kdbx

db_user

User name for database access

cs://jobs/oracle/minos.sos@user?file=./config/jobs.kdbx

db_password

Password for database access

cs://jobs/oracle/minos.sos@password?file=./config/jobs.kdbx

Explanation:

  • The jobs/oracle/minos.sos value is an example for a path to an entry in the KeePass database that holds the credentials.
  • The ./config/jobs.kdbx value is an example for a relative path to the KeePass database that holds the Credential Store.

Short Syntax

The short syntax can be used if arguments are specified with references to the Credential Store location:

Name

Required

Purpose

Example

db_url

yes

JDBC connection string

cs://jobs/oracle/minos.sos@url

db_user

yes

User name for database access

cs://jobs/oracle/minos.sos@user

db_password

yes

Password for database access

cs://jobs/oracle/minos.sos@password
credential_store_fileyesLocation of the Credential Store database file (*.kdbx)./config/jobs.kdbx
credential_store_keynoLocation of the Credential Store key file (*.key)./config/jobs.key
credential_store_passwordnoPassword of the Credential Storesecret
credential_store_entry_pathno

Folder hierarchy and entry name in the Credential Store 

/jobs/oracle

Use with JITL Mail Jobs

Use with Arguments

References to a Credential Store can be directly specified from arguments. This applies to the following JITL Mail Jobs:

References to a Credential Store

References to a credential store can be directly specified from arguments.

Full Syntax

The full syntax is used when the complete URI is specified with an argument, for example:

Name

Purpose

Example

mail.smtp.host

SMTP hostname or IP address

cs://jobs/mail/mail.sos-berlin.com@url?file=./config/jobs.kdbx

mail.smtp.user

User account for SMTP authentication

cs://jobs/mail/mail.sos-berlin.com@user?file=./config/jobs.kdbx

mail.smtp.password

Password for SMTP authentication

cs://jobs/mail/mail.sos-berlin.com@password?file=./config/jobs.kdbx

Explanation:

  • The jobs/mail/mail.sos-berlin.com value is an example for a path to an entry in the KeePass database that holds the credentials.
  • The ./config/jobs.kdbx value is an example for a relative path to the KeePass database that holds the Credential Store.

Short Syntax

The short syntax can be used if arguments are specified with references to the Credential Store location, for example:

Name

Required

Purpose

Example

mail.smtp.host

yes

SMTP hostname or IP address

cs://jobs/mail/mail.sos-berlin.com@url

mail.smtp.user

yes

User account for SMTP authentication

cs://jobs/mail/mail.sos-berlin.com@user

mail.smtp.password

yes

Password for SMTP authentication

cs://jobs/mail/mail.sos-berlin.com@password
credential_store_fileyesLocation of the Credential Store database file (*.kdbx)./config/jobs.kdbx
credential_store_keynoLocation of the Credential Store key file (*.key)./config/jobs.key
credential_store_passwordnoPassword of the Credential Storesecret
credential_store_entry_pathno

Folder hierarchy and entry name in the Credential Store 

/jobs/mail

Use with JITL SAP Jobs

TODO

Use with JITL SSH Jobs

TODO


  • No labels
Write a comment…