...
Introduction
Job, Order and Job Chain parameters conveying sensitive information can be stored in a Credential Store.
Display feature availability
StartingFromRelease | 1.12.6 |
---|
Display feature availability | ||
---|---|---|
|
Overview
- To be done ...
- 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
java
command line utility.
Behavior in JobScheduler Versions up to 1.12.5
- Job andOrder parameters cannot be substituted.The SOSKeePassDatabase class can be called in a shell Job (for master or agent), in a javascript Job (for master or agent) or in a powershell Job (for agent only).
- If the Job is run successfully:
- exit status = 0, output is sent to stdout
- If the Job ends in error:
- exit status = 99, exception output is sent to stderr
- If the Job is run successfully:
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)
Code Block | ||||
---|---|---|---|---|
| ||||
<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:
Code Block | ||||
---|---|---|---|---|
| ||||
<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: