Troubleshooting

Resolution – When using Port Monitoring software to validate the Connector Gateway connections, use one of the following methods to enable this service to work properly:

• Using a port monitoring solution – Ensure that the port monitoring software is located on a server other than the SailPoint and/or the Connector Gateway server. The proper method of using the software is to establish a connection in the same method used by SailPoint:

  Connect on the defined port +1 and on the defined port 2470, (the port defined in init.xml is 2470). This method creates a valid socket connection.

• Checking the status of Connector Gateway – This method involves the use of two telnet sessions.

  Connect on the defined port +1 and on the defined port 2470, (the port defined in init.xml is 2470). This method creates a valid socket connection.

  This should be tested to ensure that this does not interfere with active connections within your environment.

• Writing a log parser – Write a log parser to check for socket information within the logs. If the socket connections are not performing properly and are preventing the Connector Gateway to determine the proper status, enable DEBUG tracing. The following are other options to use log parser method:

  • Check the log output to see when the connection information was last updated (stale connection check). If there are no updates from the Connector Gateway within the time variable X (defined locally as it pertains to the environment), then Service. With this the Connector Gateway should be Online.

  • Write a log parser that validates the socket connection pairs for the transactions that are valid and are initiated from the IP address of the SailPoint host only. When using this method, ensure that the connection is misdirected, unclean or invalid.

Ensure that other unwanted traffic does not interfere with the normal communications in your network. You can use firewalls and logical routing to isolate traffic to and from trusted source machines and services. SailPoint recommends that you test the these alternative methods in your environment using the proper Change Management methodology as specified below:

• Develop

• Test

• Promote to production after proper testing is completed

Resolution – If any special character(s) cause problems for Mainframe Connector passwords, perform the following:

1. Change the character set to IBM1047 for Mainframe Connector-based applications as follows:

   <entry key="IBMcharacterSet" value="IBM1047"/>

2. Set the value of the <characterSet> in the init.xml file of the Mainframe connectors to the same value as that of the characterSet in the previous step:

   <characterSet>IBM1047</characterSet>

3. Restart the Connector Gateway.

Resolution – The IBM character set used must be uniform across the source XML, Connector Gateway, and Mainframes; removing anomalies at the time of conversion from one format to another as follows:

• Source XML: <entry key="IBMcharacterSet" value="IBM1047"/>

• Connector Gateway: <characterSet>IBM1047</characterSet>

• Mainframe Host Code Page: 1047

Resolution – On Connector Gateway:

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

   log4j.rootLogger = ALL, commonLog

2. Restart the Connector Gateway.

If you run a test connection during aggregation, the test connection transaction times out because the connector is busy processing the aggregation.

Resolution – To resolve this issue, configure multiple transaction servers on the connector to perform more than one transaction at a time.

Transactions take an excessive amount of time.

Resolution – If the transaction is expected to take more than 10 minutes, perform the following:

Set the smReadTimeout parameter in the source XML via Debug as follows:

<entry key="smReadTimeout" value="10"/>

The timeout value is in minutes and can be defined to read messages between SailPoint and the Mainframe connector. The default value is 10 minutes.

The following error message appears when multiple versions of Java are installed on the same computer, and the valid certification path is not found by the requested target.

Error - main, handling exception: javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

Resolution – Ensure that there is a single version of Java installed on your computer.

In the ConnectorGateway-May-2019 version of Connector Gateway release, Connector Gateway prints Java SSL logs when TLS and TRACE level logs are enabled.

• If the Connector Gateway is running as command line, then logs are printed on the console

• If the Connector Gateway is running as service (on Windows only) then logs are printed in the stdout.log file inside the log directory of Connector Gateway.

Resolution – Disable the SSL logs as follows:

• Add and set the value of the disableSSLLogs parameter to true in the init.xml file of the Connector Gateway under the <Server> tag as follows:

  <disableSSLLogs>true</disableSSLLogs>

• Set the disableSSLLogs to true using the following command:

  java -jar ConnectorGateway.jar -disableSSLLogs true

If the TLS communication channel is enabled between SailPoint and Connector Gateway, and one of the following errors is encountered:

Connection with Connector Gateway is broken

Could not find valid certificate chain

Resolution: Ensure that one of the following entries exists in the init.xml file:

• CGCertSubject – This indicates that the Connector Gateway certificate name, which is available as CN under properties, exists in the Connector Gateway certificate.

  <entry key="CGCertSubject" value="http://sailpoint.com"/>

• disableHostnameVerification – This is applicable when the Connector Gateway skips the certificate subject verification.

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

When the Connector Gateway communicates with Mainframe Connector using TLS, and if agentCertSubject or disableHostnameVerification are missing in the init.xml file, the following error message is listed in Connector Gateway logs:

java.security.cert.CertificateException: No name matching zpdt1-sysc.test.sailpoint.com found

Resolution – If TLS communication is enabled between Connector Gateway and Mainframe Connector then following entry is mandatory in the SM tag of the init.xml file:

<agentCertSubject>ENCRYPTED_VALUE</agentCertSubject>

The ENCRYPTED_VALUE can be achieved by using an encryption key mechanism or using the default encryption key supported by the connector while executing the following command:

java -jar ConnectorGateway.jar -agentCertSubject CertSubject

To skip the agent certificate subject validation, the following entry must be added in the init.xml file under the SM tag, the default value is false.

disableHostnameVerification>true</disableHostnameVerification>

While performing Test Connection or any provisioning operations, the transaction fails with the following error message:

CTS1036E R Application name UNDEFAPL specified in APPL_NAME RSSPARM parameter is not defined in Mainframe Connector.

Resolution – Provide permissions to the administrators performing the transactions.

For more information, refer to Security Configurations for Mainframe Integration Components.

CTS10480E R Provisioning Engine needs to be upgraded or ALLOW_ADMIN_WITHOUT_PSWD should be set to Y in RSSPARM.

Resolution – Upgrade to the latest Provisioning Engine.

Or

Set the ALLOW_ADMIN_WITHOUT_PSWD parameter in RSSPARM of Mainframe Connector and restart the Mainframe Connector.

For more information on the ALLOW_ADMIN_WITHOUT_PSWD parameter, refer to Security Configurations for Mainframe Integration Components.

While performing a test connection or any provisioning operations, the transaction fails with the following error message:

CTS1081E User SDDEV123 does not exist

Resolution – Ensure that the application configuration credentials are correct and the user exists on the managed system.

With correct TLS configuration for communication between Mainframe Connector and Connector Gateway the following error displays:

Timeout Exception

Resolution – Add the TLSCommWait attribute in milliseconds using SailPoint REST API:

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

Use the form-data as follows:

• Key – Connector_TLSCommWait

• value – 100

Resolution – Ensure that the Connector Name mentioned in the application configuration is in upper-case.

Test Connection displays the following error when using TLS communication:

peer not authenticated

Resolution – During TLS configuration, ensure that the certificate or the keystore / truststore path in the init.xml file is correct. If the truststore is not the default truststore on IdentityIQ then set -Djavax.net.ssl.trustStore in JAVA_OPTS to the full path of the truststore.

Resolution – Any Mainframe tools which handle x37 abends should be avoided when using the SailPoint Mainframe connector.