Page History
...
A number of JS7 - Job Templates that implement database access support support the use of a Credential Store:
A number of JITL Job Templates require credentials, for example, 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 sensitive information to be retrieved from a Credential Store. References to Credential Store entries can safely be specified with argument values.
- Credential Store
- A credential store allows the securely storage and retrieval of credentials for authentication, as well as connection details and other parameters
- See JS7 - Use of Credential Store with Shell Jobs
- See YADE Credential Store.
- Solution Outline
- Access to the Credential Store is automatically provided for JS7 - Job Templates.
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
,user
,password
,url
,attachment
. Custom field names are supported.
- frequently-used properties include Credential Store field names such as
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 UnixC:\ProgramData\sos-berlin.com\js7\agent
for Windows
- Example:
- a relative path
./config/secret.kdbx
maps toC:\ProgramData\sos-berlin.com\js7\agent\config\secret.kdbx
- a relative path
- By default this is the Agent's configuration directory, for example,
password
- optionalthe password for access to the Credential Store file.
It is recommended that this parameter ia not used and that instead a
key_file
is used 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.
Anchor | ||||
---|---|---|---|---|
|
JS7 - JITL Database Jobs can can access a Credential Store in the following ways:
- when being used with using a Hibernate configuration file,
- by use of using arguments
Use with a Hibernate Configuration File
The Hibernate access layer is used for database access and therefore requires configuration files for is frequently used with database credentials. The access information such as accounts, passwords and JDBC URLs etc. are is specified in with the Hibernate configuration files.
Generally it is preferable not to use passwords to access a database directly 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 , users can add your a password to a KeePass Credential Store and add a reference for to the Credential Store to your their Hibernate configuration file.
...
This applies to the following JITL Database Jobs:
References to a Credential Store
Syntax for Hibernate Configuration Files
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 full syntax is used when the complete URI is specified with each element of the Hibernate configuration file:
Code Block | ||||
---|---|---|---|---|
| ||||
<?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 |
...
- 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 is used when the credential store items are to short syntax can be used in if the hibernate Hibernate configuration to provide the details about the credential store:
...
file includes explicit references to the Credential Store:
Code Block | ||||
---|---|---|---|---|
| ||||
<?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">
.kdbx</property> => path to the Credential Store database file<property name="hibernate.sos.credential_store_key_file">./config/secret.key</property>
=> path of to the key file for the Credential Store<property name="hibernate.sos.credential_store_password">secret</property>
=> password of the Credential Store database file<property name="hibernate.sos.credential_store_entry_path">/secret/database/reporting</property>
=> specifies the folder hierarchy and entry name in the Credentials Store database file
When adding the Credential Store reference to the Hibernate configuration file as above then credentials can be retrieved from the Credential Store by using the following elements:
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:
Code Block | ||||
---|---|---|---|---|
| ||||
<?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/ |
...
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.
Use with Arguments
The JITL Database Jobs support the following arguments:
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 for 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 |
---|
Name
Purpose
Required
Example | |
---|---|
| JDBC connection string |
Either a DB URL or a reference to a Credential Store is used.
User and password for database access can be specified by arguments or a reference to a Credential Store is used.
jdbc:oracle:thin:@localhost:1521:XE
| ||
| User name for database access | cs://jobs/oracle/minos.sos@user?file=./config/jobs.kdbx |
| Password for database access |
|
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 |
---|---|---|---|
| yes | JDBC connection string |
|
| yes |
db_user
User name for database access |
scott
cs://jobs/oracle/minos.sos@user | ||
| yes | Password for database access |
tiger
cs://jobs/oracle/minos.sos@password | ||
credential_store_file | yes | Location of |
the Credential Store database file (*.kdbx) |
./config |
/jobs.kdbx | ||
credential_store_key_file | no | Location of |
the Credential Store key file (*.key) |
./config/ |
jobs.key |
JITL SAP Jobs can
- Starting Point
- Users frequently operate jobs that require credentials, e.g. to access a database, a file transfer SFTP server etc.
- Such jobs are implemented as simple shell jobs.
- 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. Therefore credentials cannot be forwarded by parameters to jobs.
- 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 stored with parameter values.
- Credential Store
- A credential store allows the secure storage and retrieval of credentials for authentication, as well as connection and other parameters, for a detailed features and supported products see YADE Credential Store.
- Solution Outline
- Access to the credential store is provided by a Java class that can be loaded from shell jobs and from JS7 - Job Templates.
- The Java class is parameterized with the path that identifies the requested entry from the credential store.
Usage
JS7 Agents provide the com.sos.keepass.SOSKeePassDatabase
Java class that can be invoked
- in a shell job by calling the
java
command line utility with the class name:- If the class is executed successfully:
- return code = 0, output is sent to stdout
- If execution of the class ends in error:
- return code = 99, exception output is sent to stderr
from the command line like this:
java com.sos.keepass.SOSKeePassDatabase "cs://server/SFTP/homer.sos@password?file=credential_store.kdbx"
When invoking the class then the path to the entry in the credential store has to be specified.
- If the class is executed successfully:
- by use of a shell script provided with JS7 Agents
- for Unix environments:
$JS7_AGENT_HOME/bin/agent_credential_value.sh "cs://server/SFTP/homer.sos@password?file=credential_store.kdbx"
- for Windows environments:
%JS7_AGENT_HOME%\bin\agent_credential_value.cmd "cs://server/SFTP/homer.sos@password?file=credential_store.kdbx"
- The script hides the call to the
java
command line utility.
- for Unix environments:
- A call to the
SOSKeePassDatabase
class syntactically uses a single parameter string that holds the URI and a number of query parameters:
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
. Custom field names are supported.- starting with JITL-585 the
attachment
property is supported
- starting with JITL-585 the
- for detailed explanations of available properties see the Using Credential Store to securely store authentication, connection and other parameters article.
- frequently used properties include credential store field names such as
- The URI based syntax includes the protocol
Query Parameters
Standard Parameters
file
- required- the path to the credential store database file. This file can be stored anywhere in the file system.
- The path can be specified either relatively or absolutely. As a path separator both forward slashes and backslashes can be used. For example:
- Relative paths are considered with respect to the Agent's working directory, see
JS7_AGENT_WORK_DIR
from the JS7 - Job Environment Variables
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- a key file for the credential store database file.
- If this parameter is set:
- this path can be specified either relatively or absolutely. See explanation for the
file
parameter. - An exception will be raised if the .key file cannot be found.
- this path can be specified either relatively or absolutely. See explanation for the
- If this parameter is not set:
- a <credential_store_database_filename_without_extension>.key file such as credential_store.kdbx -> credential_store.key will be looked up in the directory where the credential store database file is located.
- The .key file will be used if it exists.
- An exception will be raised if a .key file is not found and the
password
parameter is not used.
- a <credential_store_database_filename_without_extension>.key file such as credential_store.kdbx -> credential_store.key will be looked up in the directory where the credential store database file is located.
ignore_expired
- optional (boolean 0-1), default: 0- ignore_expired=0 - an exception is raised if the entry has expired.
- ignore_expired=1 - expiration of an entry is ignored.
attachment
- optional (boolean 0-1)- attachment=1 - a attachment field is used.
Advanced Parameters
...
create_entry
=0 - an exception is raised if the entry cannot be found.create_entry
=1 - creates an entry if it does not exist.- an exception is raised if the root group of the
cs://<entry_path>
URI does not match the credential store root group. - creates the full path to the entry if it does not exist.
- an exception is raised if the root group of the
...
- set value of a string property:
cs://<entry_path>@<property_name>?...&set_property=<value>
<property_name>
property exists:- property value will be updated.
<property_name>
property does not exist:<property_name>
property will be created with the given value.
- set value of a binary property:
cs://<entry_path>@<property_name>?...&set_property=<file path>&attachment=1
<property_name>
property exists:- property value will be updated with the
<file path>
file content.
- property value will be updated with the
<property_name>
property does not exist:<property_name>
binary property will be created with the<file path>
file content.
cs://<entry_path>@attachment?...&set_property=<file path>
- creates a new binary property with the given file content if it does not exist (property name is a file name), or updates the binary property value from the given file content.
credential_store_password | no | Password of the Credential Store | secret |
credential_store_entry_path | no | Folder hierarchy and entry name in the Credential Store | /jobs/oracle |
Anchor | ||||
---|---|---|---|---|
|
Use with Arguments
References to a Credential Store can be directly specified from arguments. This applies for 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 |
---|---|---|
| SMTP hostname or IP address |
|
| User account for SMTP authentication | cs://jobs/mail/mail.sos-berlin.com@user?file=./config/jobs.kdbx |
| Password for SMTP authentication |
|
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 |
---|---|---|---|
| yes | SMTP hostname or IP address |
|
| yes | User account for SMTP authentication | cs://jobs/mail/mail.sos-berlin.com@user |
| yes | Password for SMTP authentication | cs://jobs/mail/mail.sos-berlin.com@password |
credential_store_file | yes | Location of the Credential Store database file (*.kdbx) | ./config/jobs.kdbx |
credential_store_key_file | no | Location of the Credential Store key file (*.key) | ./config/jobs.key |
credential_store_password | no | Password of the Credential Store | secret |
credential_store_entry_path | no | Folder hierarchy and entry name in the Credential Store | /jobs/mail |
Anchor | ||||
---|---|---|---|---|
|
Use with Arguments
References to a Credential Store can be directly specified from arguments. This applies to the following JITL SSH 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 |
---|---|---|
| This argument specifies the user account to be used when connecting to the SSH server. |
|
| This argument specifies the user account's password for authentication by the SSH server and has to be specified if the password authentication method is specified with the | cs://jobs/ssh/ssh.sos-berlin.com@password?file=./config/jobs.kdbx |
| This argument specifies the path and name of a private key file used for authentication with an SSH server. This argument has to be specified if the publickey authentication method is specified with the |
|
proxy_user | The value of this argument specifies the user account for authentication with the proxy server that is used to connect to the SSH server. | cs://jobs/ssh/ssh-proxy.sos-berlin.com@user?file=./config/jobs.kdbx |
proxy_password | This argument specifies the password for the proxy server user account if a proxy is used to connect to the SSH server. | cs://jobs/ssh/ssh-proxy.sos-berlin.com@password?file=./config/jobs.kdbx |
Explanation:
- The
jobs/mail/ssh.sos-berlin.com x
value is an example for the 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 | Example |
---|---|
|
|
| cs://jobs/ssh/ssh.sos-berlin.com@password |
| cs://jobs/ssh/ssh.sos-berlin.com@attachment |
credential_store_file | ./config/jobs.kdbx |
credential_store_key_file | ./config/jobs.key |
credential_store_password | secret |
credential_store_entry_path | /jobs/ssh |
...
- does not create any output for the binary property set with the
set_property
.
...