Configure TLS/mTLS Between SailPoint Mainframe Connector and the Connector Gateway (CG)

This section describes how to configure Transport Layer Security (TLS) and mutual TLS between SailPoint Mainframe Connector and CG.

  1. TLS: Configuration between the SailPoint Connector and CG.

  2. Mutual TLS: Configuration between CG and Mainframe system.

TLS and Mutual TLS require certificates for authentication. Certificates can be self-signed or issued by a Public Key Infrastructure (PKI).

This following steps use keytool and a self-signed certificate example.

Prerequisites

  • Configure the SailPoint Connector.

  • Install and configure the SailPoint Connector Gateway.

  • Configure at least one virtual appliance cluster and successfully test the connection. For instructions, refer to the Virtual Appliance Reference Guide.

Validate the CG Connection

Before configuring TLS and Mutual TLS, validate the connection to the CG and enable TLS in the source configuration.

  1. Go to Admin > Connections > Sources.

  2. Select the Source you configured.

  3. Go to Connection Settings, and disable the Enable TLS  toggle.

  4. Go to Review and Test and select Test Connection to validate the connection.

    Important:
    Test Connection must be successful.

  5. After the connection is successful, go to Connection Settings and enable the Enable TLS toggle.

  6. Select Save.

Create the Encryption Key File

Important:
The following steps apply only to CG 2025 and later. They do not apply to CG versions earlier than Connector Gateway-Jun-2025.

  1. In the CG deployment directory, create an empty .txt file.

  2. Change the name to EncryptionKeyFile or another suitable name.

  3. Add a key value to the file and save it.

    For more details on key value, refer to Details of Encryption Key File.

The file stores the symmetric key that encrypts sensitive values in init.xml.

Caution:
If the encryption key file is not provided, the CG uses a hard-coded default key which is not recommended for production environment.

Configure the Encryption Key File in init.xml

  1. In the init.xml, set the <EncryptionKeyFile> parameter to the absolute path of the encryption key file, including the file name.

Configure TLS (CG as TLS Server)

  1. Create and configure a server certificate on the CG. The Connector validates the server certificate during the TLS handshake.

Note:
A client certificate is not required.

  1. Use the keytool to run the following command to generate the key pair and keystore:

    keytool -genkey -keyalg RSA -alias OneWayCGAuth -keystore keystore.jks -storepass password -validity 360 -keysize 2048

    Use the settings:

    • Algorithm: RSA, 2048-bit

    • Validity: 360 days (or per policy).

    • keystore format: JKS,

    • Alias and passwords: User defined (for example, OneWayCGAuth, password).

  2. Generate the certificate using the Common Name (CN), for example OneWayCGAuth. This value is used later in the Certificate Subject / CGCertSubject on the SailPoint Mainframe Connector.

  1. Run the following command to export the server certificate (CER):

keytool -export -alias OneWayCGAuth -storepass password -file server.cer -keystore keystore.jks

The certificate is stored in server.cer.

Configure TLS and keystore in init.xml

  1. From the CG deployment directory that contains ConnectorGateway.jar, run the following command to configure the keystore:

java -jar ConnectorGateway.jar -keystorepass <storepass> -keypass <keypass> -keystore "<absolute_path_to_keystore.jks>"

Important:
The command stores encrypted keystorePass and keyPass (keystore path) into init.xml.

  1. Run the following command to enable TLS:

java -jar ConnectorGateway.jar -enableCGtoPE2TLS "true"

  1. Restart the CG to apply the changes. After the configuration, init.xml contains entries similar to the following:

Configure the Connector

  1. Copy the server.cer to /home/sailpoint/certificates.

  2. Restart the Client Connector Gateway (CCG) service on the virtual appliance.

  3. Open the source.

  4. Go to Connection Settings.

  5. In the Certificate Subject, enter the Common Name (CN) of the CG certificate, for example: OneWayCGAuth.

  6. Select Save.

  7. Go to Review and Test and select Test Connection to validate the connection.

    Important:
    Test Connection must be successful.

Configure Mutual TLS

After you configure the TLS successfully, configure Mutual TLS to enable client certificate authentication.

In Mutual TLS, the Connector presents a client certificate and the CG validates it against a truststore.

Generate the Client Certificate for the CG Connection

  1. Generate a dedicated keystore and export the client certificate on the ISC virtual appliance.

  2. Run the following command to generate the key pair and keystore:

keytool -genkey -keyalg RSA -alias TwoWayServerAuth -keystore keystore.jks -storepass password -validity 360 -keysize 2048

  1. Run the following command to export the certificate:

keytool -export -alias TwoWayServerAuth -storepass password -file server.cer -keystore keystore.jks

  1. Generate the certificate using the Common Name (CN), for example: TwoWayServerAuth. This value is used later as PE2CertSubject in CG configuration.

Configure the Connector

  1. Copy the server.cer and keystore.jks to /home/sailpoint/certificates.

    Rename the files if necessary to avoid overwriting existing files.

  2. Restart the CCG service on virtual appliance.

  3. Copy the server.cer to the CG and optionally copy the keystore.jks for reference.

    The certificate is now imported into the CG truststore.

Configure CG truststore and init.xml

  1. Create a directory on the CG. For example: ConnectorGateway_location\TLS\CG\truststore.

  2. Copy the JVM cacerts file into the truststore directory. Example location: JAVA_HOME/lib/security

  3. Run the following command to import the SailPoint connector certificate into the cacerts truststore:

    keytool -import -v -trustcacerts -alias TwoWayServerAuth -file server.cer -keystore cacerts -keypass <password>

    Note:
    If trust or certificate chain warnings appear, try another JVM's cacerts file or make sure that the certificate chain is complete.

  4. Run the following command to add the Mutual TLS configuration to init.xml:

    java -jar ConnectorGateway.jar -enablePe2TLSAuth true -trustStorePE2TLSAuth "<absolute_path_to_truststore_cacerts>" -PE2CertSubject TwoWayServerAuth

  5. Restart the CG.

Configure Mutual TLS in SailPoint Mainframe Connector

  1. Go to Configuration Settings and enable the Enable Mutual TLS toggle.

  2. In KeyStore Path, enter the path to the Keystore file on the Virtual Appliance. For example: /home/sailpoint/certificates/keystore.jks

  3. In Keystore Password, enter the password for the specified Keystore.

  4. In Key Password, enter the password for the private/secret key.

  5. Select Save.

  6. Go to Review and Test and select Test Connection to validate the connection.

Summary of init.xml Elements

Attribute Name

Description

encryptionKeyFile

Specifies the path to file that contains 16/24/32 - byte encryption key used to encrypt sensitive values in init.xml. Required for CG 2025 and later.

keystore / keystorePass / keyPass

Specify the CG server certificate for TLS. These values are encrypted when generated using ConnectorGateway.jar.

enableCGtoPE2TLS

Enables TLS on CG for connections from SailPoint Connectors.

enablePe2TLSAuth

Enables client certificate authentication for Mutual TLS.

trustStorePE2TLSAuth

Specifies the path to the truststore (for example, cacerts) that contains SailPoint Connector certificates.

PE2CertSubject

Specifies the Common Name (CN) of the allowed SailPoint Connector certificate. This value is stored in encrypted form in init.xml.