Using Credential Store to securely store authentication, connection and other parameters

Introduction

The Credential Store (CS) allows sensitive data to be encrypted and stored securely and independently of the application(s) such as YADE and the JobScheduler YADE JITL Jobs that use this data. Access to the CS is only possible with access methods such as a key file and/or password.
The CS requires the use of a .kdbx database and the installation of a kdbx-compatible user interface such as "KeePass 2" or "KeePass-X".
The advantage of using a CS is that the CS stores sensitive information such as credentials in a standardized, secure and fully encrypted database and sensitive authentication information is not exposed in use. Applications access the CS database by using password, encryption-key file or a combination of both.
The CS can be used to securely store information of parameters, database connection URLs, private key files and other sensitive data.

Scope

This article describes the use of the Credential Store with the YADE Client.

A description of the use of the Credential Store with the YADE JITL job can be found in the Jobs JADEJob & JADE4DMZJob article.

Configuration Procedure

The examples presented in this article are based on the simple file transfer example described in the The YADE Client Command Line Interface - Tutorial 1 - Getting Started article. This tutorial describes the configuration required to download a number of files from a online server provided by the SOS GmbH and save these files on the user's local file system. Using this server means that users can get a working example up and running with a minimum of effort. A simplified version of the configuration used in the tutorial (only specifying FTP) is available as a download: sos-berlin_demo_2_local.xml. Instructions for installing and configuring the YADE Client can be found in the YADE - Tutorials article.

The configuration provided in the download file will cause six files in the root server folder to be copied to a local /jade_demo/transfer_receive folder, generating the target folder in the user's home or profile directory if required and permissions are available. The files will be transferred by FTP and authentication for the server (user name and password) is specified in the download file.

Installing and configuring the Credential Store

KeePass 2 has been used in the current article to implement the credential store database. The installation of and use of KeePass is described on the Keepass Web Site.

For the examples described in the current article the following database was configured (on a Windows system):

Path: %USERPROFILE%\jade_demo\keepass\demo_cred_store.kdbx
Master Password: sos

In addition a Master Key file (not used in the example below) can be generated using the Files/Change Master Key KeePass menu option and then selecting the Show expert options checkbox (shown greyed out in the following screenshot).

Adding Data to the Credential Store

A group named ftp has been used for the current example along with the entry "demo on test.sos-berlin.com".

The following information can be retrieved from standard CS fields:

Title: Target server name or IP address
User name: The user identification of a user who is authenticated for the operation.
Password: Assigned password for a user account or passphrase for a private key.
URL: .....
File Attachment: Files such as PGP or SSH private key files can be stored as attachments. YADE will retrieve the contents of the attached file at run-time - no intermediate or temporary files are created when reading attachments.

Configuration of an individual entry in the CS:

The following information was specified for the example in the database:

Database: demo_database
Group: ftp
Title: demo_on_test.sos-berlin.com
User name: demo
Password: demo
URL: test.sos-berlin.com (Alternatively, the IP address could have been specified here.)

Integrating the Credential Store in a File Transfer Configuration

The use of the Credential Store is specified in YADE Client file transfer configuration files, which are written in XML. We recommend using the SOS XML Editor to edit these files. Instructions for downloading, installing and using the XML Editor are linked from this page.

In the remainder of the current article, it is assumed that readers have made themselves familiar with the organization of the YADE Client file transfer configurations into Profiles and Fragments. This is described in The YADE Client Command Line Interface - Tutorial 1 - Getting Started article mentioned above.

The following example uses the XML configuration from and adds the necessary configuration elements required to replace the "standard" authentication elements with elements stored in the Credential Store.

The following XML configuration elements are required to specify the use of the Credential Store:

A CredentialStoreFragments element at the same level in the XML hierarchy as the Protocol Fragments elements.
- This element can have one or more child Credential Store Fragment elements (described below).
A CredentialStoreFragment element that is referenced from the ProtocolFragment. This Fragment specifies the location of and authentication required for the Credential Store.
- Password, key file and combined password/key file authentication methods are possible.
A CredentialStoreFragmentRef element as a child element of the Protocol Fragment element - in the current example this is the FTPFragment.
The values of the connection and authentication elements are modified to refer to elements stored within the Credential Store.

Addressing the Credential Store

Parameters stored in the example Credential Store database Entry are addressed in the CredentialStoreFragment XML element as follows:

The CSEntryPath element is used to specify the path in the Credential Store to the Credential Store Entry:
- cs://demo_database/ftp/ (where demo_database is the Database name and ftp the (optional) name of the Group, as specified above).

The Credential Store Entry parameters are accessed using the following syntax, where demo_on_test.sos-berlin.com is the Title that has been set for the Credential Store Entry.

Hostname: demo_on_test.sos-berlin.com@url (where @url specifies the URL element stored in the database )
Account: test.sos-berlin.com@user (where @user specifies the User name element stored in the database)
Password: test.sos-berlin.com@password (where @password specifies the Password element stored in the database)

The parts of the XML configuration relevant to the use of the Credential Store are shown in the following screenshot of the XML Editor:

Running the YADE Client with the Credential Store

The use of the Credential Store is contained within the settings file and is not exposed when calling the YADE Client. For example, on Windows systems, the YADE Client could be called for the current example using:

Call on Windows systems

C:\Program Files\sos-berlin.com\jade\client\bin>jade.cmd -settings="%USERPROFILE%\jade_demo\sos-berlin_demo_2_local.xml" -profile="ftp_server_2_local_cs"

The output produced when successful:

Output

C:\Program Files\sos-berlin.com\jade\client\bin>jade.cmd -settings="%USERPROFILE%\jade_demo\sos-berlin_demo_2_local.xml" -profile="ftp_server_2_local_cs"

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+                       START  : JADE.CMD                         +
+                       -----------------                         +
+ DATE     : 17.04.2018 14:56:51,26
+ HOSTNAME : JS-PC
+ USER     : aa
+ CALL     : C:\Program Files\sos-berlin.com\jade\client\bin\jade.cmd -settings="C:\Users\aa\jade_demo\sos-berlin_demo_2_local.xml" -profile="ftp_server_2_local_cs"
+                                                                 +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

main INFO  14:56:54,679   (SOSDataExchangeEngineMain.java:76) ::Execute SOSDataExchange - Kommandozeilenprogram startet ....
main INFO  14:56:54,711   (SOSDataExchangeEngine.java:536) ::showBanner
************************************************************************
*                                                                      *
*                     YADE - Managed File Transfer                     *
*                     -----www.sos-berlin.com-----                     *
*                                                                      *
************************************************************************
  Version                 = 1.12.3-SNAPSHOT (2018-04-15 23:09, revision f156fa1144fe219789e9bf2ad1d3a4b52a68cd24) Copyright 2003-2018 SOS GmbH Berlin
  Date                    = 2018-04-17 14:56:54
  SettingsFile            = C:\Users\aa\jade_demo\sos-berlin_demo_2_local.xml
  Profile                 = ftp_server_2_local_cs
  Operation               = copy
  Transactional           = false  
+------------Source------------
  | Protocol              = ftp
  | Host                  = test.sos-berlin.com
  | IP                    = 93.157.51.161
  | User                  = demo
  | Password              = ***
  | Passive               = false
  | TransferMode          = binary
  | Directory             = ./
  | FileSpec              = .*
  | ErrorWhenNoFilesFound = true
  | Recursive             = false
  | Remove                = false

  +------------Target------------
  | Protocol              = local
  | Host                  = JS-PC
  | IP                    = 192.11.0.85
  | Directory             = C:\Users\aa\jade_demo\transfer_receive/
  | OverwriteFiles        = true

main INFO  14:56:55,164   (SOSVfsFtpBaseClass.java:242) ::doConnect SOSVfs_D_0102: Verbunden mit Rechner 'test.sos-berlin.com' ³ber Port-Nummer '21'.
main INFO  14:56:55,539   (SOSVfsFtpBaseClass.java:958) ::login (demo@test.sos-berlin.com:21) SOSVfs_D_133: Benutzer 'demo' eingeloggt.
main INFO  14:56:55,695   (SOSVfsFtpBaseClass.java:1295) ::transferMode SOSVfs_D_123: Antwort des FTP-Servers ['binary']: '200 Type set to I'.
main INFO  14:56:56,148   (SOSDataExchangeEngine.java:897) ::setInfo 6 files found for regexp '.*'.
main INFO  14:56:56,945   (SOSDataExchangeEngine.java:788) ::printState SOSJADE_I_0101: Es wurden 6 Dateien ³bertragen
main INFO  14:56:56,961   (SOSDataExchangeEngine.java:359) ::showResult
*************************************************************************
 Ausf³hrungsstatus                 = Ohne Fehler.
 Erfolgreiche ▄bertragungen        = 6
 ▄bersprungene ▄bertragungen       = 0
 Fehlgeschlagene ▄bertragungen     = 0
 letzter aufgetretener Fehler      =
*************************************************************************
main INFO  14:56:56,976   (SOSDataExchangeEngineMain.java:78) ::Execute Execute - Programm wurde ohne Fehler beendet

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+                        END   : JADE.CMD                         +
+                        ----------------                         +
+ DATE     : 17.04.2018 14:56:57,03
+ HOSTNAME : JS-PC
+ USER     : aa
+ CALL     : C:\Program Files\sos-berlin.com\jade\client\bin\jade.cmd -settings="C:\Users\aa\jade_demo\sos-berlin_demo_2_local.xml" -profile="ftp_server_2_local_cs"
+ EXIT     : 0
+                                                                 +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

As with all YADE jobs, the number of successful file transfers can be seen in the log file.

Space shortcuts

Page tree