Introduction
Job, Order and Job Chain parameters conveying sensitive information can be stored in a Credential Store.
This feature is similar to the method used by the YADE file transfer job (and command line utility) to store information such as credentials and described in the YADE Credential Store article.
FEATURE AVAILABILITY STARTING FROM RELEASE 1.12.6
Overview
- 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 or by use of the API Interface.
- Security Considerations
- Secure information from job parameters and order parameters should not be disclosed, e.g. written to log files, therefore the solution does not store secure information in parameters.
- Instead a run-time interface is offered that allows to retrieve secure information from a credential store.
- 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 API jobs implemented e.g. for JavaScript, PowerShell etc.
- The Java class is parameterized with the path that identifies the requested entries from the credential store.
- This solution can be operated with JobScheduler Master and with Agents.
Usage
- The SOSKeePassDatabase Java class 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
- If the class is executed successfully:
- in a JavaScript Job
- by directly instantiating the Java class from JavaScript.
- if execution of the class ends in error then an exception is raised.
- in Powershell Jobs (for use with Agents only) by calling the java command line utility with the class name:
- A return code is provided similar to Shell jobs.
- in a Shell Job by calling the java command line utility with the class name:
- The class can be invoked
from the command line like this:
java com.sos.keepass.SOSKeePassDatabase "cs://server/SFTP/homer.sos@user?file=credential_store.kdbx"
When invoking the class then the path to the entry in the credential store is specified.
- by use of a script provided with JobScheduler e.g. for Unix environments:
$SCHEDULER_HOME/bin/jobscheduler_credential_value.sh "cs://server/SFTP/homer.sos@user?file=credential_store.kdbx"- The script hides the call to the
javacommand line utility.
Syntax
The following query parameters can be set:
- file - required
- the path to the credential store database file.
- this path can be specified either relatively or absolutely. For example:
- relative values for a Master are with respect to the SCHEDULER_DATA directory.
- relative values for an Agent are with respect to the SCHEDULER_HOME (install) directory.
- password - optional
- the password for the credential store database file.
- key_file - optional
- If this parameter is set:
- this path can be specified either relatively or absolutely. See the file example.
- If this parameter is not set:
- a <file_without_extension>.key file such as: mystore.kdbx -> mystore.key) will be sought in the directory of the file .
- a .key file will be used if it is found
- an exception will be thrown if a .key file is not found - even if the password query is not set.
- a <file_without_extension>.key file such as: mystore.kdbx -> mystore.key) will be sought in the directory of the file .
- If this parameter is set:
- ignore_expired - optional, default: 0
- ignore_expired=0 - an exception is thrown when the entry expires
- ignore_expired=1 - expiring of an entry is ignored
- attachment - optional, default: 0
- attachment=0 - a String field is read
- attachment=1 - a file attachment field is read and returned as new String (bytes).
Examples
JavaScript Job (master/agent) Example
Two methods can be used:
- com.sos.keepass.SOSKeePassDatabase.getProperty(uri)
- com.sos.keepass.SOSKeePassDatabase.getBinaryProperty(uri)
JavaScript Job Example (master/agent)
<job order="no" stop_on_error="no">
<script language="java:javascript"><![CDATA[
function getCredentialStoreProperty(uri){
try{
return Packages.com.sos.keepass.SOSKeePassDatabase.getProperty(uri);
}
catch (e) {
throw new Error("can't get property: "+e.message);
}
}
function exportCredentialStoreAttachment2File(uri, targetFile){
var fos = null;
try{
var data = Packages.com.sos.keepass.SOSKeePassDatabase.getBinaryProperty(uri);
fos = new Packages.java.io.FileOutputStream(targetFile)
fos.write(data);
} catch (e) {
throw new Error("["+targetFile+"]can't write attachment to file: "+e.message);
}
finally{
if(fos !== null){
fos.close();
}
}
}
function spooler_process(){
var file = "config/live/JITL-473-cs/kdbx-p.kdbx";
spooler_log.info("--- get string property ---");
var property = "server/SFTP/homer.sos@user";
var uri = "cs://"+property+"?file="+file+"&password=test";
var val = getCredentialStoreProperty(uri);
spooler_log.info("["+property+"]=" + val);
spooler_log.info("--- get binary property as string ---");
property = "server/SFTP/homer.sos@homer.privat.dsa";
uri = "cs://"+property+"?file="+file+"&password=test&attachment=1";
val = getCredentialStoreProperty(uri);
spooler_log.info("["+property+"]=" + val);
spooler_log.info("--- get binary property as byte array and write to file ---");
property = "server/SFTP/homer.sos@homer.privat.dsa";
uri = "cs://"+property+"?file="+file+"&password=test";
var targetFile = "D:/my_homer.privat.dsa";
exportCredentialStoreAttachment2File(uri,targetFile);
spooler_log.info("["+property+"] written to " + targetFile);
return false;
}
]]></script>
<run_time />
</job>
Powershell Job (agent) Example
Only the com.sos.keepass.SOSKeePassDatabase main method can be used:
Powershell Job (agent) Example
<job order="no" stop_on_error="no" process_class="/Agent">
<script language="powershell"><![CDATA[
function Get-CredentialStoreProperty([string] $uri) {
$command = "java"
if (![string]::IsNullOrEmpty(${env:JAVA_HOME})){
$command = "${env:JAVA_HOME}\bin\$command"
}
$arguments = @("com.sos.keepass.SOSKeePassDatabase", $uri)
$startInfo = New-Object System.Diagnostics.ProcessStartInfo
$startInfo.FileName = $command
$startInfo.RedirectStandardError = $true
$startInfo.RedirectStandardOutput = $true
$startInfo.UseShellExecute = $false
$startInfo.WindowStyle = 'Hidden'
$startInfo.CreateNoWindow = $true
$startInfo.Arguments = $arguments
try{
$process = New-Object System.Diagnostics.Process
$process.StartInfo = $startInfo
$process.Start() | Out-Null
$stdout = $process.StandardOutput.ReadToEnd()
$stderr = $process.StandardError.ReadToEnd()
$process.WaitForExit()
}
catch{
throw "Failed $($startInfo.FileName): $error"
}
if ($process.exitCode -ne 0) {
throw "Failed with exit code $($process.exitCode): $stderr"
}
$stdout
}
$file = "D:/jobscheduler.1.x/jobscheduler/data/1.12.x.x64-snapshot/config/live/JITL-473-cs/kdbx-p.kdbx";
$spooler_log.info("--- get string property with exception handling ---");
$property = "server/SFTP/homer.sos@user";
$uri = "cs://"+$property+"?file="+$file+"&password=test";
$val = Get-CredentialStoreProperty($uri);
$spooler_log.info("["+$property+"]=" + $val);
$spooler_log.info("--- get string property without exception handling ---");
$val = java com.sos.keepass.SOSKeePassDatabase $uri
$spooler_log.info("["+$property+"]=" + $val);
$spooler_log.info("--- get binary property as string with exception handling and formatted output ---");
$property = "server/SFTP/homer.sos@homer.privat.dsa";
$uri = "cs://"+$property+"?file="+$file+"&password=test&attachment=1";
$val = Get-CredentialStoreProperty($uri);
$spooler_log.info("["+$property+"]=" + $val);
$spooler_log.info("--- get binary property as string without exception handling ---");
$val = java com.sos.keepass.SOSKeePassDatabase $uri
$spooler_log.info("["+$property+"]=" + $val);
]]></script>
<run_time />
</job>
Shell Job (master/agent) Example
Only the com.sos.keepass.SOSKeePassDatabase main method can be used: