File Transfer

 View Only

Configuring Certificate based User Authentication in IBM Connect:Direct File Agent

By Ramkumar Panchanatham posted Mon October 11, 2021 11:15 AM

Co-authored by Ankit Modi

We are in a world where security aspects play a vital role. Customers are always keen to ensure that the security of their applications are properly implemented. Customers set some mandates when it comes to any kind of connectivity and one such mechanism is to strengthen the security by enabling TLS. When it comes to Connect:Direct File Agent it does connects to the Connect:Direct Server on its API port to watch and trigger processes. The current File Agent User Interface offers API Connection configuration however it does not support Secure Connection to Connect:Direct Server and Certificate based authentication mechanism. In this blog, we will understand how one can configure the File Agent to enable Secure API Connection and Certificate based authentication using the suggested workaround method. Please be aware that by API, I am referring that file agent connects to java API of CD and not CD webservice.

For this blog, I have deployed Connect:Direct V6.1.0.0 and File Agent V1.4.0.1 on Windows platform. Below are the high-level steps that we need to perform,

  • User Account Configuration in File Agent
  • Create a Keystore for File Agent
  • Create a Trust Store for File Agent
  • Update Secure+ Configuration
  • User Account Configuration in Connect:Direct
  • Launch the File Agent

User Account Configuration in File Agent

Step 1

To enable certificate-based authentication we first need to create an External Login File for the File Agent. To create the external login file, we will be using the Java Connection Utility (JCU) and the Connect Direct Java Application Interface (CDJAI) jar file.

  • Open Command Prompt in Administrator mode
  • Navigate to your File Agent Installation Path – “\IBM\FileAgent\”
  • Utilize the java executable file that resides in your File Agent jre directory and execute the below command,

          \jre\bin\java.exe -classpath CDJAI.jar -fcddef.jcu

          CDJAI.jar           Connect Direct Java Application Interface jar

          -f                     →   Denotes a file name parameter

          cddef.jcu         →    External Login File


  • Once you execute the above command you will be prompted to enter the below information of your Connect Direct Server


          Node Name       CD Node Name

          IP Address       →  IP Address of the machine where your CD is installed

          User Id             →  We are enabling certificate-based authentication hence this user id will not have any significance.
                                             Because the common name used in the certificate will be considered as the actual username to be used for connection with the server                                               which we will be performing in upcoming steps. However, User Id is a mandatory parameter hence a dummy user id
                                             value can be provided here.

          Password           As we are enabling certificate-based authentication, dummy password value can be provided here

          Protocol           →  Your input should be the TLS version info and we will be using TLS12


Step 2

Since JCU doesn’t support entering empty password we had to enter the value for it in previous step. However, empty password is required to trigger the certificate-based authentication on the Connect:Direct server. So as a workaround, navigate to your file agent installation path, open cddef.jcu file in a text editor and remove all characters after "2=" from the line starting with User.

Step 3

Now that, we have created the External Login File, let’s update the file agent configuration to use this cddef.jcu as a login file. To do this, open your File Agent wizard in administrator mode and,

  • Set the API Userid parameter as “jcu”
  • Though API hostname DNS and API port parameters are mandatory they will be ignored by File Agent and the connection information will be loaded from the external JCU login file which we created in previous steps.

Create a Keystore for File Agent

If you have the User’s key certificate already, then you can just add that key once you create the keystore for File Agent. In this blog, I have captured the steps to be used for a Self-Signed Certificate. Execute the below command to create self-signed certificate and a new keystore.

  • Navigate to your File Agent Installation Directory “\IBM\FileAgent\”
  • Utilize the keytool executable available in your file agent jre folder and execute the below command

          jre\bin\keytool.exe -genkey -alias cduser -keyalg RSA -keystore keystore.jks

          -genkey            Generates a Key

          -alias              →  Alias name of the entry to process. Provide the common name here so that it can be configured as a user
                                           later in Connect Direct   Server.

          -keyalg           →  Key Algorithm Name
          -keystore        →  Keystore Name

  • Now that you have created your Key Certificate, export the certificate to a file so that it can be used as a CA Root in later steps


          jre\bin\keytool.exe -exportcert -alias cduser -keystore keystore.jks -file cacduser.pem -rfc

          -exportcert          Read a certificate from Keystore

          -alias                 →  Key entry with an associated certificate

          -file                    →  Output File name

Create a Trust Store for File Agent

Next step is to create a Trust Store for File Agent in its installation path. This entire configuration is to enable certificate-based authentication with Connect Direct API server. Hence, in this trust store you must import the CA Root and CA Intermediate (in this case it will be the self-signed certificate) of your CD Server. In simple words, you must export the certificate from your CD Secure+ configuration and import it to this File Agent truststore. We will follow the similar steps to perform this.

          jre\bin\keytool.exe -importcert -file cacdserver.pem -keystore truststore.jks

          -importcert      →  Denotes importing a certificate or certificate chain

          -file                 →  Input Certificate file. In this case your CD Sever certificate

          -keystore        →  Trust store name

Update Secure+ Configuration

  • Launch your Secure+ Admin Tool
  • Import the User Certificate which was created and exported under the section “Create a Keystore for File Agent”
  • Open the .Client record in your Secure+ Admin Tool configure it for TLS1.2 protocol and Enable Client Authentication
  • If you have not configured your .Local record, then you can configure key Certificate Label and Cipher Suites information here


User Account Configuration in Connect:Direct

Follow the below steps to create a user for the Certificate-based authentication.

  • Create a new user and provide the username as the “common name” which you provided while creating the certificate
  • Enable the below options for this user,
    • Allow Client Certificate Authentication
    • Allow Process to run using Service Account

Launch the File Agent

Before launching the file agent, you have let the File Agent know that it needs to use the keystore and trust store while it gets launched.

  • One way is to specify the key and trust store properties (-D) on the java command line when launching File Agent
  • Another approach is to update your cdfa.lax and cdfa$.lax files in your File Agent installation path with below parameters.
  • Add the above arguments to the property in both the files

  • Alternatively, for either platform, specify these settings in an environment variable named IBM_JAVA_OPTIONS

CDFA Log image shown below displays that the File Agent started successfully and was able to scan the watch directories and submit the corresponding processes to Connect Direct Server.

Connect Direct Process Statistics

You are now ready to Run Your File Agent using secure and certificate-based authentication mode. Hope this blog was helpful.