Using a Credential Store for Job, Order and Job Chain Node Parameters

Introduction

Job, Order and Job Chain parameters conveying sensitive information can be stored in a Credential Store. FEATURE AVAILABILITY STARTING FROM RELEASE 1.12 This feature is similar to the method used by the YADE file transfer job (and command line utility) store information such as passwords.

A Credential Store can be used to store sensitive information that is used by the .
YADE allows use of a credential store as explained in the YADE Credential Store article.

Desired Behavior

Users would like to store sensitive information that should be used by job and order parameters in a credential store similar to YADE.
This includes:
- global specification of the credential store location (the credential store file path) and access method (password, key file).
- parameters reference credentials a special syntax such as cs://<path>@<value>stored with
  - Example
```
<job>
    <params>
        <param name="db_password" value="cs://databases/mysql_localhost@password"/>
    </params>
    ...
</job>
```
- to apply parameter values from a credential store to job, order and node parameters.
- substituted parameter values to be excluded from logging.

Behavior in JobScheduler Versions up to 1.12.5

Job/Order parameters are not substituted.
The SOSKeePassDatabase class can be called in a shell Job (master/agent), in a javascript Job (master/agent) or in a powershell Job (agent).
- 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

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:
  - cs://databases/mysql_localhost@password?file=config/cs/mystore.kdbx
  - cs://databases/mysql_localhost@password?file=C:/jobscheduler/data/config/cs/mystore.kdbx
- Relative values for a Master are relative to the SCHEDULER_DATA directory.
- Relative values for an Agent are relative 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.
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