Configure TLS Between SailPoint and the Connector Gateway

Before establishing the TLS communication channel with the Connector Gateway, the Mainframe Connector validates the authenticity of the Connector Gateway.

To implement this, add the CGCertSubject entry key in the source via SailPoint REST API as follows:

PATCH https://sailpoint.api.identitynow.com/v3/sources/:id

Note
For more information on SailPoint's REST APIs, refer to Best Practices: REST API Authentication and REST API - Update Source (Partial) in the SailPoint Developer Community.

In the body of the PATCH, set form-data values as follows:

  • key – connector_CGCertSubject
  • value – sailpoint.com

The Mainframe Connector checks the CN of the subject of the certificate with the value provided in the source configuration as mentioned in the above entry key. The CGCertSubject parameter is configurable only through the source configuration.

If the CGCertSubject is not provided, then the Mainframe Connector validates the CN of the subject against the FQDN of the machine hosting the Connector Gateway. This functionality is configurable in the source configuration using the disableHostnameVerification parameter. If the value of disableHostnameVerification parameter is set to true, then the Mainframe Connector doesn't validate the CN of the subject name.

For example:

<entry key="disableHostnameVerification" value="true"/>

Default value is false.

Perform the following steps to enable TLS between SailPoint and the Connector Gateway:

  1. Set the enableCGtoPE2TLS parameter to true in the init.xml file as follows:

    Copy 
    java -jar ConnectorGateway.jar -enableCGtoPE2TLS "true" -keyStore
    "keystorePath" -keyStorePass "keystorePassword" -keyPass
    keyPassword"

    Where:

    Variables

    Description

    keystorePath

    The keystorePath variable is the location for a keystore.jks which it has been generated using a keytool utility, specifically on the Connector Gateway machine.

    keystorePassword

    The keystore.jks file is protected with a password. This password enables access to the keystore.jks file once authenticated.

    keyPassword

    Key password is for the private/secret key password, in case keystore password fails then keytool uses keypassword to recover keys.

  2. The keystorePassword and keyPassword are encrypted by the Connector Gateway while updating the init.xml file. An encryption key can be defined specific to site and used to encrypt the data. The encryptionKeyFile path must be added to the init.xml file as follows:

    <encryptionKeyFile>path</encryptionKeyFile>

    For example:

    <encryptionKeyFile>C:\FileName</encryptionKeyFile>

    The key length should be 16, 24, or 32 bytes.

    Note

    • If encryptionKeyFile is not provided or the length is anything other than the specified bytes, then the Connector Gateway encrypts/decrypts sensitive data by using the default key. Ensure you recycle the keys and secure this file by giving proper access control.

    • The encryptionKeyFile mentioned above is for Mainframe Integrations. For more information, see Frequently Asked Questions (FAQ).

  3. Add the root CA cert in /home/sailpoint/certificates directory of the VA and restart the CCG service.

    For additional information on importing the certificate into VA truststore CA certs, refer to TLS Configuration on Virtual Appliances

Configure Mutual TLS Authentication Between SailPoint and the Connector Gateway

After you enable TLS authentication, you can enable mutual TLS in the SailPoint connector, then configure it on the SailPoint and Connector Gateway hosts.

Mutual TLS enables the Connector Gateway to validate the authenticity of Identity Security Cloud at the same time that Identity Security Cloud validates the Connector Gateway itself.

To enable mutual TLS authentication between the Connector Gateway and Identity Security Cloud:

  1. From the source configuration page in Identity Security Cloud, select Edit Configuration and select the Connection Settings tab.

  2. Select Enable Mutual TLS to enable the feature in the connector.

    Note
    This option doesn't display unless you select Enable TLS first.

  3. Configure the following attributes in the fields provided:

    Variables

    Description

    keystorePath

    The keystorePath variable is the location for a keystore.jks which it has been generated using a keytool utility. Typically, this is the Virtual Appliance.

    keystorePassword

    The keystore.jks file is protected with a password. This password enables access to the keystore.jks file once authenticated.

    keyPassword

    Key password is for the private/secret key password, in case keystore password fails then keytool uses keypassword to recover keys.

  4. Select Save.

    You may now exit the source configuration.

  5. Export the certificate from the Keystore in the Virtual Appliance, then import it to the trustStorePE2TLSAuth path on the Connector Gateway host.

    Note
    If the certificate is not available, create a Certificate Signing Request (CSR) on the Virtual Appliance. Then, submit the CSR to a trusted internal or third-party Certificate Authority (CA) for signing. Ensure that the CA is on a trusted root CA list in the Connector Gateway machine.

  6. The Connector Gateway must validate the CN of the certificate subject against the value provided for the PE2CertSubject parameter in the init.xml file in the Connector Gateway.

    Important
    Don't set the PE2CertSubject value in the initialization XML file directly. It must be set only by using the method described in this step.

    Set the PE2CertSubject value using the following command:

    java -jar ConnectorGateway.jar - PE2CertSubject <VALUE>

    For example:

    java -jar ConnectorGateway.jar - PE2CertSubject CertSubject

    A sample subject of a certificate is:

    CN = CertSubject OU = Engineering O = SailPoint L = PUN S = MH C = IND

    By running this command, the Connector Gateway encrypts the PE2CertSubject value and stores it in the init.xml file under the SERVER tag as follows:

    <PE2CertSubject>ENCRYPTED_VALUE</PE2CertSubject>

  7. (Optional) You can disable the hostname verification functionality with the disablePE2HostnameVerification attribute in the init.xml file.

    If you set the value of the disablePE2HostnameVerification attribute to true, then the Connector Gateway doesn't validate the CN of the subject name. The default value is false.

  8. Use the following command to set the enablePE2TLSAuth parameter to true. The default value is false. This sets the truststore path:

    java -jar ConnectorGateway.jar – enablePE2TLSAuth "true" - trustStorePE2TLSAuth "<truststorePath>"

    Consider the following for this command:

    • enablePE2TLSAuth – Only used if enableCGtoPE2TLS is set to true.

      When this is set to true, the Connector Gateway validates the authenticity of Identity Security Cloud. This is set to false by default.

    • trustStorePE2TLSAuth – The full path of the truststore for Identity Security Cloud authentication in the Connector Gateway.