Page History
...
Sensitive information that is used in job scripts can be stored in a Credential Store and retrieved at run-time.
This feature is similar to the approach used by the YADE file transfer job (and command line utility) to store credentials with the YADE Credential Store.
- Starting Point
- Users frequently operate jobs that require credentials, for example, to access a database, an SFTP server etc.
- Such jobs are implemented as shell jobs.
- Security Considerations
- Sensitive information in jobs should not be hard-coded, should not be used from parameters and should not be disclosed, for example written to log files.
- Instead, a run-time interface is offered that allows retrieval of 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 storing and retrieval of credentials for authentication, for connections and other parameters, for 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.commons.credentialstore.keepass.SOSKeePassDatabase
Java 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.commons.credentialstore.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 a detailed description of the 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:
cs://databases/mysql_localhost@password?file=config/credential_store.kdbx
cs://databases/mysql_localhost@password?file=C:/ProgramData/sos-berlin.com/js7/agent/config/credential_store.kdbx
- Relative paths are considered with respect to the Agent's working directory, see
JS7_AGENT_WORK_DIR
from the JS7 - Job Environment Variables article.
password
- optional- the password for the Credential Store database file.
- It is recommended that this parameter is not used and that instead a
key_file
is used 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:
- the path can be specified either relatively or absolutely. See explanation for the
file
parameter above. - An exception will be raised if the .key file cannot be found.
- the 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
- optional (boolean 0-1), default:0
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 top-level group of the
cs://<entry_path>
URI does not match the Credential Store top-level group. - creates the full path to the entry if it does not exist.
- an exception is raised if the top-level group of the
set_property
- optional- 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:
...&set_property=<file path>&attachment=1cs://<entry_path>@<property_name>?
<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 content of the given file if the property does not exist (property name is a file name); updates the binary property value from the content of the given file.
- set value of a string property:
stdout_on_set_binary_property
- optional (Boolean 0-1), default:0
stdout_on_set_binary_property
=0- does not create any output for the binary property set with the
set_property
.
- does not create any output for the binary property set with the
stdout_on_set_binary_property
=1- creates output to stdout for the binary property set with the
set_property
.
- creates output to stdout for the binary property set with the
Examples
Job Example for Unix
Code Block | ||||
---|---|---|---|---|
| ||||
#!/usr/bin/bash JS7_CREDENTIAL_VALUE=`"$JS7_AGENT_HOME/bin/agent_credential_value.sh" "cs://jobs/SFTP/sftp_server@password?file=$JS7_AGENT_CONFIG_DIR/jobs.kdbx"` RC=$? if [ $RC -ne 0 ] then exit $RC fi echo $JS7_CREDENTIAL_VALUE |
Explanation:
- The script
agent_credential_value.sh
is available from the Agent's./bin
folder in the installation directory. The environment variable$JS7_AGENT_HOME
is automatically provided. - The credential store file is located in the
./config
directory of the Agent. The environment variable$JS7_AGENT_CONFIG_DIR
is automatically provided. - The credential value to be retrieved is returned to stdout by the script. The example makes use of the
$JS7_CREDENTIAL_VALUE
environment variable to hold the output to stdout of the script, i.e. it receives the credential value. - As a prerequisite the
JAVA_HOME
environment variable has to be set. As the Agent is operated for Java the job script will find this environment variable if it has been exported when starting the Agent.
Job Example for Windows
Code Block | ||||
---|---|---|---|---|
| ||||
@rem Example 1: use of built-in variable %JS7_CREDENTIAL_VALUE% @call "%JS7_AGENT_HOME%\bin\agent_credential_value.cmd" "cs://jobs/SFTP/sftp_server@password?file=%JS7_AGENT_CONFIG_DIR%\jobs.kdbx" if ERRORLEVEL 1 exit /b %ERRORLEVEL% @echo %JS7_CREDENTIAL_VALUE% @rem Example 2: output to stdout @call "%JS7_AGENT_HOME%\bin\agent_credential_value.cmd" "cs://jobs/SFTP/sftp_server@password?file=%JS7_AGENT_CONFIG_DIR%\jobs.kdbx" stdout if ERRORLEVEL 1 exit /b %ERRORLEVEL% |
Explanation:
- The script
agent_credential_value.cmd
is available from the Agent's./bin
folder in the installation directory. The environment variable%JS7_AGENT_HOME%
is automatically provided. - The credential store file is located in the
./config
directory of the Agent. The environment variable%JS7_AGENT_CONFIG_DIR%
is automatically provided. - The credential value to be retrieved is returned via the built-in %
JS7_CREDENTIAL_VALUE%
environment variable by the script (seeExample 1: use of built-in variable %JS7_CREDENTIAL_VALUE%
).%JS7_CREDENTIAL_VALUE%
contains the last row of output to stdout.
- The additional argument
stdout
(seeExample 2: output stdout
) controls whether any output is forwarded to stdout. - As a prerequisite the
JAVA_HOME
environment variable has to be set.