Frequently Asked Questions (FAQ)

Refer to this section for answers to frequently asked questions related to all the Mainframe Connectors.

Communication diagram for the Mainframe Connectors in IdentityIQ

  • Connector Gateway – The Connector Gateway is an independent process running on a server. It is responsible for receiving requests from the Provisioning Engine, then sending those requests to the Mainframe Connector one after another on a pair of socket channels.  The socket channel opened between the Connector Gateway and the Mainframe Connector on z/OS is a persistent TCP/IP channel.  When the Connector Gateway is started, it tries to establish a connection (two socket channels on the Mainframe Connector on z/OS port and port+1) with the Mainframe Connector.

  • Provisioning Engine – The Provisioning Engine is part of IdentityIQ and is responsible for processing multiple requests received from the IdentityIQ server. Each request (T1,T2,...Tn) maintains its dedicated TCP/IP channel to the Connector Gateway to process the respective request. The socket channel, once opened, is maintained until the request is completed.  The communication between the Provisioning Engine, the Connector Gateway, and the Mainframe Connector on z/OS can be secured by enabling TLS encryption.

  • Mainframe Connector on z/OS – The Mainframe Connector on z/OS — as shown in the above diagram — executes the requests (Aggregation, Provisioning Entitlements, Role Assignments, and Password Management) sent by the Provisioning Engine on the system.

    The Mainframe Connector on z/OS executes the changes received from the Connector Gateway and sends the response to update the status in SailPoint.

    The RACF, ACF2, and TSS applications have connectors to manage each system. Each application requires the Connector Gateway and the respective the Mainframe Connector on z/OS.

By design, the IdentityIQ server starts a new thread and then terminates that thread after the request is completed for every request. The Mainframe Connector on z/OS expects a pair of open, persistent socket channels between the Mainframe Connector and its client. All requests must be performed over those channels.

The Connector Gateway opens a pair of persistent socket channels with the Mainframe Connector on z/OS. It can handle concurrent requests originating from one or more of the Provisioning Engine instances. The Connector Gateway forwards these requests to the Mainframe Connector and sends responses received from the Mainframe Connector to the Provisioning Engine.

No, you must use the Connector Gateway released with your SailPoint product.

Enabling TLS communication between the Provisioning Engine and the Connector Gateway requires the definition of a few parameters, including the keystore password and the key password in the init.xml file of the Connector Gateway as shown in the follow in example:

java -jar ConnectorGateway.jar -keyStore <keystore filepath> -keyStorePass <keystore password> -keyPass <key password>

The keystore password (keyStorePass), key password (keyPass), and the subject name of the optional agent certificate (agentCertSubject) are considered sensitive information which must be encrypted before saving them in the init.xml file.

One-way encryption can't be used to encrypt these parameters as the Connector Gateway must decrypt them while establishing the socket connection. So, a two-way encryption algorithm is used. This algorithm requires a key to encrypt and decrypt the data.

There is an option to externalize that key in a file (encryptionKeyFile). You can set that key in a file and provide read access to the Connector Gateway. The key used to set the path of the file that stores the encryption key (encryptionKeyFile) can be set in the init.xml file as follows:

<encryptionKeyFile>full_path</encryptionKeyFile>

With this set, you can define a secured unique key.

Important
It is your responsibility to ensure that the key is secure. You should be able to change the key at any point if it's ever compromised. If key is changed or modified then you must execute the above command to define new values so that they are updated in the init.xml file.

Note

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

    For example:

    • 16 bytes – C38A9B8CCAF37167

    • 24 bytes – C38A9B8CCAF371673017B17D

    • 32 bytes – C38A9B8CCAF371673017B17D0AAE8396

      If the encryption key file is not configured, then the hard-coded key is used to encrypt the sensitive data.

  • Keys can be generated online or you can write your logic to generate one. The only requirement is that it is 16, 24, or 32 bytes in length.

A new version of Connector Gateway is released with every IdentityIQ and patch release. This means you must upgrade the Connector Gateway at the same time you upgrade IdentityIQ. SailPoint recommends that you use the Connector Gateway shipped with your version of IdentityIQ.

The Connector Gateway is shipped with each IdentityIQ release or patch. SailPoint recommends that you use the Connector Gateway shipped with your version of IdentityIQ.