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.6

This feature is similar to the method used by the YADE file transfer job (and command line utility) to store information such as passwords and described in the YADE Credential Store article.

Overview

Typical parameter information that could be stored in a credential store includes:
- global specification of the credential store location (the credential store file path) and access method (password, key file).

Parameters referencing credentials are stored using a special syntax cs://<property>@<value>:

Example

<job>
    <params>
        <param name="db_password" value="cs://databases/mysql_localhost@password"/>
    </params>
    ...
</job>

Parameter values from a credential store can be applied to Job, Order and Job Chain node parameters.
Substituted parameter values are not logged.

Behavior in JobScheduler Versions up to 1.12.5

Job and Order 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

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 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.
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