We recommend configuring the Synthetic Server to use SSL to secure network connections. This page describes how to create a custom keystore and then configure the Synthetic Server to use it to implement SSL.

Set Up a Custom Keystore for the Synthetic Server

The following sections describe and show an example of how to create a custom RSA security certificate, generate a new JKS keystore, and sign the certificate.

Install Prerequisite Libraries

Make sure the following libraries are installed on the Synthetic Server:

  • keytool
  • openssl

Create a Certificate and Keystore

Use the keytool command to create a keystore that uses RSA encryption then generate a certificate signing request (CSR).

The following steps show you an example of how to do both.

  1. Log in to the Synthetic Server machine.

  2. From a command-line shell, navigate to the root directory of the Synthetic Server:

    cd <synthetic_server_root>
    BASH

  3. Create a new keystore with a new unique key pair that uses RSA encryption:

    <path_to_jre>/jre/bin/keytool -genkey -keyalg RSA -validity <validity_in_days> -alias 'synthetic-server' -keystore ./mycustom.keystore
    BASH

    This creates a new public-private key pair with an alias of "synthetic-server". You can use any value you like for the alias. The "first and last name" required during the installation process becomes the common name (CN) of the certificate. Use the name of the server.

  4. Configure the keystore by entering the information requested at the command prompt.
  5. Specify a password for the key store. You need to configure this password in the Synthetic Server configuration file later.  

  6. Generate a certificate signing request (CSR):

    <path_to_jre>/jre/bin/keytool -certreq -keystore ./mycustom.keystore -file /tmp/synthetic-server.csr -alias 'synthetic-server'
    BASH

    This generates a certificate signing request based on the contents of the alias; in the example, it is "synthetic-server".

Sign and Install the Signed Certificate

Once you have a CSR, you request a Certificate Authority to sign it and then install the signed certificate.

The following steps are a continuation of the process from Create a Certificate and Keystore:

  1. Send the output file from the last step (/tmp/synthetic-server.csr in this example) to a Certificate Authority for signing.

  2. Install the certificate for the Certificate Authority used to sign the .csr file:

    <path_to_jre>/jre/bin/keytool -import -trustcacerts -alias myorg-rootca -keystore ./mycustom.keystore -file /path/to/<CA-root-cert>
    BASH

    This command imports your CA's root certificate into the keystore and stores it in an alias called "myorg-rootca".

  3. Install the signed server certificate as follows:

    <path_to_jre>/jre/bin/keytool -import -keystore ./mycustom.keystore -file /path/to/<signed-cert>  -alias 'synthetic-server'
    BASH

    This command imports your signed certificate over the top of the self-signed certificate in the existing alias; in the example, it is "synthetic-server".

  4. Import the root certificate to the other platform components connecting to the Synthetic Server through HTTPS:

    keytool -import -trustcacerts -alias <alias_name> -file mycert.cer -keystore <complete_path_to_cacerts.jks> 
    BASH

Configure the Synthetic Server to Use the Keystore

Follow the steps below to configure the Synthetic Server to use the signed certificate and its password.

  1. Edit the Synthetic Scheduler configuration file at <installation directory>/conf/synthetic-scheduler.yml and add the applicationConnectors object shown below under server:

    server:
    ...
    applicationConnectors:
        - type: https
          port: <port>
          keyStorePath: <path to JKS files>
          keyStorePassword: <jks file password>
          validateCerts: false
    TEXT

    If you don't already have a signed certificate, see Create and Sign an RSA Security Certificate. 

  2. Edit the Synthetic Shepherd configuration file at <installation directory>/conf/synthetic-shepherd.yml and add the applicationConnectors object shown below under server:

    server:
    ...
    applicationConnectors:
        - type: https
          port: <port>
          keyStorePath: <path to jks file>
          keyStorePassword: <jks file password>
          validateCerts: false
    TEXT
  3. Restart the Synthetic Server.
  4. Verify the connection to the HTTPS port.