TLS Communication

Completely secure the connection with the source by enabling and configuring Transport Level Security (TLS) protocol between the each of the components that make up your system.

Enabling TLS Communication

The Transport Layer Security (TLS) protocol provides encryption, authentication and integrity to all applications. To use TLS-secured communication for the Mainframe Connector, TLS communication must be defined and configured in the following relevant components:

• TCP/IP in the system where the Mainframe Connector will be active
• Connector Gateway
• SailPoint

Enabling Traces

Enabling logs for Cluster enables debug level logs for all sources which use that cluster.

On the Connector Gateway

1. Edit the log4j2.properties file on the Connector Gateway by setting the following line:

   log4j2.rootLogger = DEBUG, commonLog

2. Restart the Connector Gateway.

Configure TLS Between the Connector Gateway and Mainframe

To enable TLS communication between the Connector Gateway and Mainframe, the Connector Gateway must validate the CN of the subject of certificate against the value provided in the agentCertSubject parameter in the init.xml file. The agentCertSubject parameter must only be set by using the following command:

java -jar ConnectorGateway.jar -agentCertSubject <VALUE>

For example:

java -jar ConnectorGateway.jar -agentCertSubject CertSubject

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

<agentCertSubject>ENCRYPTED_VALUE</agentCertSubject>

If agentCertSubject is not specified then the Connector Gateway validates the CN of the certificate subject against the FQDN of the machine hosting the Mainframe Connector.

To enable TLS between the Connector Gateway and the Mainframe Connector:

1. Set up AT-TLS on the Mainframe where the Mainframe Connector (Agent) is installed. The certificate must be exported from the Mainframe and imported into the Connector Gateway machine.

2. Use the following command to set the enableCGtoAgentTLS parameter to true and set the truststore path:

   java -jar ConnectorGateway.jar -enableCGtoAgentTLS "true" -trustStore "truststorePath"

   where trustStore is the full path of truststore.

   Note

   All the components the Connector Gateway, CCG, and the Mainframe Connector must be restarted after modifying the configurations.

Configure Mutual TLS Authentication Between the Connector Gateway and Mainframe

After you enable and configure TLS authentication, you can configure mutual TLS authentication on the Connector Gateway and Mainframe hosts.

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

To enable mutual TLS authentication between Mainframe and the Connector Gateway:

1. In the init.xml file, set the enableCGTLSAuth parameter to true and provide supporting authentication credentials:

   Important

   Don't set the keyStorePassCGTLSAuth and keyPassCGTLSAuth parameter values directly in the init.xml file. They must be set only by using the method in this step.

   java -jar ConnectorGateway.jar -enableCGTLSAuth "true" -keyStoreCGTLSAuth "keystorePath" -keyStorePassCGTLSAuth "keystorePassword" -keyPassCGTLSAuth "keyPassword"

   Consider the following for these commands:

   Variables	Description
   enableCGTLSAuth	Only used if enableCGtoAgentTLS is set to true. When this is set to true, Mainframe validates the authenticity of the Connector Gateway. This is set to false by default.
   keyStoreCGTLSAuth	This is a file location where a keytool utility generated keystore.jks file can be found. Typically this is in the Connector Gateway host. This keystore.jks file is used by Mainframe to authenticate the Connector Gateway.
   keyStorePassCGTLSAuth	The keystore.jks file is protected with a keystorePassword. The password grants access to the keystore.jks file upon successful mutual TLS authentication.
   keyPassCGTLSAuth	This private/secret keyPassword is a fallback authentication method used if the configured keystore password fails, and the keytool needs to recover the keys.

   Note

   The keystorePassword and keyPassword values are encrypted by the Connector Gateway while updating the init.xml file.

2. Copy or transfer the certificate from the Connector Gateway host to the Mainframe dataset and add it as a trusted certificate.

3. Set the HandshakeRole ServerWithClientAuth and ClientAuthType Required values in the Mainframe AT-TLS policy.

   For more information on these values, refer to Implementing AT-TLS Policy for Mainframe Connector Communication.

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).

The 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

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 encryptionKeyFile.

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

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.

   Screenshot

   

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.

2. 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).

3. 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.

   Screenshot

   

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

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

   Screenshot

   

   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:

   Important

   Before you run commands that update init.xml, make sure encryptionKeyFile is configured in init.xml.

   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.

2. Run the following command to enable TLS:

   java -jar ConnectorGateway.jar -enableCGtoPE2TLS "true"

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

   Screenshot

   

Configure the Connector for TLS

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.

   Screenshot

   

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 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

3. Run the following command to export the certificate:

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

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

Configure the Connector for Mutual TLS

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:

   Important

   Before you run commands that update init.xml, make sure encryptionKeyFile is configured in init.xml.

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

5. Restart the CG.

   Screenshot

   

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.

   Screenshot

   

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

Summary of init.xml Elements

Configuring TLS on the Mainframe Connector

Secured communication to the Mainframe Connector must be implemented using an AT-TLS policy. An AT-TLS policy states that communication must be implemented on a port defined to Mainframe as non-secured. The TLS processing is done by TCPIP and is transparent to the Mainframe Connector. For more information, refer to Implementing AT-TLS Policy for Mainframe Connector Communication.

The secured communication is implemented using server authentication.

Common implementation procedure to set up TLS for the Mainframe Connector

1. A valid server certificate with its associated server private key must be defined. This certificate must be signed by a trusted Certificate Authority's (CA).
2. The server certificate and the CA certificate must be connected to a key ring.
3. The server certificate signed by CA must be transferred (using FTP with ASCII mode) to the client and installed there to be used for certificate verification by the TLS handshake process.

Implementing AT-TLS Policy for Mainframe Connector Communication

For detailed information about implementing AT-TLS policy, refer to the Application Transparent Transport Layer Security Data Protection chapter of z/OS Communications Server IP Configuration Guide.

The required policy attributes for AT-TLS policies are listed below. You can copy and paste them into your AT-TLS policy.

• Local Port Range - ports defined in Mainframe Connector as non-secured
• Direction = Inbound
• TLS Enabled = On
• TLS v1.1 = On
• TLS v1.2 = On

• # For one way TLS

  Handshake Role = Server

• # For mutual TLS

  Handshake Role = ServerWithClientAuth

• # For one way TLS

  Client Authorization Type = PassThru

• # For mutual TLS

  Client Authorization Type = Required

• Application Controlled = Off

• Secondary Map = Off
• The name of the certificate created for the secured communication and the name of the key ring to which the server certificate and the CA certificate are connected, must be specified.

Sample File for AT-TLS Policy

RULE for Mainframe Connector CTSGATE

####################################################

TTLSRule CTSGATE
{
LocalAddr ALL
RemoteAddr ALL
LocalPortRange 2470-2471
Direction Inbound
Priority 255 # highest priority rule
Userid CTSGATE
TTLSGroupActionRef GrpAct_CTSGATE
TTLSEnvironmentActionRef GrpEnv_CTSGATE
TTLSConnectionActionRef GrpCon_CTSGATE
}
TTLSGroupAction GrpAct_CTSGATE
{
TTLSEnabled On
Trace 7
HandshakeRole Server
}
TTLSEnvironmentAction GrpEnv_CTSGATE
{
Trace 7
HandshakeRole Server
EnvironmentUserInstance 0
TTLSKeyringParmsRef PrmKeyRing_CTSGATE
TTLSEnvironmentAdvancedParmsRef PrmEnvAdv_CTSGATE
}
TTLSEnvironmentAdvancedParms PrmEnvAdv_CTSGATE
{
TLSv1.1 On
TLSv1.2 On
#Comment out the following line out if enabling Mutual TLS
ClientAuthType PassThru
#To Enable Mutual TLS between Mainframe and Connector Gateway use below
#ClientAuthType Required
}
TTLSConnectionAction GrpCon_CTSGATE
{
#Comment out the following line out if enabling Mutual TLS
HandshakeRole Server
#If you are enabling Mutual TLS between Mainframe and Connector Gateway use below
#HandshakeRole ServerWithClientAuth
TTLSCipherParmsRef PrmCipher_CTSGATE
TTLSConnectionAdvancedParmsRef PrmConAdv_CTSGATE
CtraceClearText Off
Trace 7
}
TTLSConnectionAdvancedParms PrmConAdv_CTSGATE
{
ApplicationControlled Off
CertificateLabel CTSGATE
SecondaryMap Off
}
TTLSCipherParms PrmCipher_CTSGATE
{
# supported cipher suites - we used a wide list, that should be decreased according to specific needs V3CipherSuites TLS_DH_DSS_WITH_DES_CBC_SHA
V3CipherSuites TLS_DH_RSA_WITH_DES_CBC_SHA
V3CipherSuites TLS_NULL_WITH_NULL_NULL
V3CipherSuites TLS_RSA_WITH_NULL_MD5
V3CipherSuites TLS_RSA_WITH_NULL_SHA
V3CipherSuites TLS_RSA_EXPORT_WITH_RC4_40_MD5
V3CipherSuites TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5
V3CipherSuites TLS_RSA_WITH_DES_CBC_SHA
V3CipherSuites TLS_DHE_DSS_WITH_DES_CBC_SHA
V3CipherSuites TLS_DHE_RSA_WITH_DES_CBC_SHA
V3CipherSuites TLS_RSA_WITH_AES_256_CBC_SHA256
V3CipherSuites TLS_RSA_WITH_AES_256_CBC_SHA
V3CipherSuites TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
V3CipherSuites TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
V3CipherSuites TLS_RSA_WITH_AES_128_CBC_SHA256
V3CipherSuites TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256
V3CipherSuites TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256
V3CipherSuites TLS_DHE_RSA_WITH_AES_128_CBC_SHA256
V3CipherSuites TLS_DHE_DSS_WITH_AES_128_CBC_SHA256
V3CipherSuites TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
V3CipherSuites TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
V3CipherSuites TLS_RSA_WITH_AES_128_CBC_SHA
V3CipherSuites TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA
V3CipherSuites TLS_ECDH_RSA_WITH_AES_128_CBC_SHA V3CipherSuites TLS_DHE_RSA_WITH_AES_128_CBC_SHA
V3CipherSuites TLS_DHE_DSS_WITH_AES_128_CBC_SHA V3CipherSuites TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
V3CipherSuites TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
V3CipherSuites TLS_RSA_WITH_AES_128_GCM_SHA256
V3CipherSuites TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256
V3CipherSuites TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256
V3CipherSuites TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
V3CipherSuites TLS_DHE_DSS_WITH_AES_128_GCM_SHA256
V3CipherSuites TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA
V3CipherSuites TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA
V3CipherSuites TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA
V3CipherSuites TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA
}
TTLSKeyringParms PrmKeyRing_CTSGATE
{
Keyring CTSRING
}

• Relevant entities - TCPIP and PAGENT
• In TCPIP, AT-TLS must be active
• PAGENT must be up
• PAGENT requires a policy
• Refresh definitions: after member/file is updated, use the F PAGENT,UPDATE or F PAFGENT,REFRESH
• CTSGATE does not have to be restarted when the policy is changed
• CA certificate must be sent to Connector Gateway side.

Documentation Feedback

Feedback is provided as an informational resource only and does not form part of SailPoint’s official product documentation. SailPoint does not warrant or make any guarantees about the feedback (including without limitation as to its accuracy, relevance, or reliability). All feedback is subject to the terms set forth at https://developer.sailpoint.com/discuss/tos.