Skip to content

Configuring ACF2 for Integration

This section contains reference information and configuration tasks you'll need to complete to configure the SailPoint ACF2 connector after establishing the connection.

Installing and Configuring Connector Gateway

The Connector Gateway can be installed on a UNIX/Windows computer with network connectivity to both SailPoint and the ACF2 Connector.

Create an installation directory on the computer where the Connector Gateway will run and extract the contents of the ConnectorGateway-releaseVersion.zip file included with this release of SailPoint, where releaseVersion is the version of the Connector Gateway.

Before You Begin

  • Java Development Kit is required to install Connector Gateway, Oracle Jdk 11 and 17 and OpenLogic Jdk 11 and 17 are recommended.

  • After upgrading to the latest version of the Connector Gateway, interceptions are no longer stored in a file or read from a file. As a result, pending interceptions or interceptions not sent to the Provisioning engine (which were stored in a file by the previous version of the Connector Gateway) will be invalid.

    • The Connector Gateway and the ACF2 Connector can be started / stopped in any order.
    • If there is a firewall between the Connector Gateway and the ACF2 Connector, then the port and port +1 on which ACF2 Connector is listening must be opened.

Installation steps for the Connector Gateway must be followed only if you want to configure the Connector Gateway as a service.

Note

You can download components for which you have an active license from SailPoint. However, the availability of a component for download does not grant you a license to use a component or entitle you to use a component for which you do not have an active license. Please contact your Account Representative or CSM for more information.

Supported Operating Systems

The Connector Gateway provides support for the following operating systems:

  • SUSE Linux Enterprise Server version 15
  • Windows Server version 2022 and 2025

Hardware Sizing Considerations

Use the information below to determine the hardware resource allocations required by your Mainframe deployment. For a more detailed explanation, refer to the IdentityIQ Hardware Sizing Guide.

Connector Gateway Resource Allocation

You need to provide a separate host to run the Connector Gateway for the ACF2 connector. Dedicating a virtual machine (VM) as a host for all of the Connector Gateway instances provides a simple approach and a redundancy/backup strategy for this part of the infrastructure.

Regardless of your overall IdentityIQ footprint, SailPoint suggests using the same resources as a medium UI server compute resource target for a single Connector Gateway instance. For example, if a medium footprint calls for 4 CPUs, 8 GB of memory, and 50 GB of storage for a UI server. For more information about Connector Gateway, refer to Connector Gateway (CG) and Mainframe Connectors - FAQ and Troubleshooting.

Note

Connector Gateway can be installed on systems with other ancillary SailPoint products (like IQService). However, be sure that the system has dedicated resources (TCP ports, for example) to support all products to appropriately.

Installing Connector Gateway

Install the Connector Gateway on a Windows or UNIX system.

  1. Download the Connector Gateway from the Mainframe Connectors Downloads page.

  2. Unzip the ConnectorGateway-<releaseVersion>.zip file in the temporary directory.

    The following files are extracted:

    • init.xml
    • install.bat
    • update.bat
    • log4j.properties
    • ConnectorGateway.jar
    • ConnectorGateway64.exe
    • log4j-core-2.26.0.jar
    • log4j-api-2.26.0.jar
    • log

  3. Set JAVA_HOME environment variable to the root directory of your JDK installation.

  4. Run the following batch file to install Connector Gateway on 64-bit systems:

    • install.bat

    Verify that the SailPointConnectorGateway_<service name> service has been installed, where <service name> is the name of the service to which the Connector Gateway is connected during the installation of the connector.

    For example, you can use 20 as a value for server entries.

  5. Edit the init.xml file and set the host and port details for the Mainframe Connector and the listening port for the Connector Gateway in the Server tag. For more information on parameters in the init.xml file, refer to Example init.xml File.

    Note

    Restart the Connector Gateway after init.xml file is modified.

    The parameters in the init.xml file can also be set using the command line as follows:

    java -jar ConnectorGateway.jar -smHostname <MF Host> -smPort <MF Agent Port> -serverPort <Connector Gateway Port> -characterSet <Character Set>

    Note

    All the parameters in the init.xml file can be set using the above command. You can set one or more parameters at a time.

    To update Service Name edit the install.bat file and rename SERVICE_NAME_SUFFIX variable.

  6. Start the SailPointConnectorGateway_<service name> service.

  7. To provide heap memory settings for the Java Virtual Machine (JVM) pass the values like below:

    install.bat JvmMsValue JvmMxValue i.e. install.bat 32 512

    update.bat JvmMsValue JvmMxValue i.e. update.bat 32 512

    Note

    • JvmMx Stands for Maximum heap size which Sets the maximum amount of memory the JVM can allocate for the heap. default is 512MB
    • JvmMs Stands for: Minimum heap size which Sets the initial memory allocation for the heap when the JVM starts. default is 32 MB

  8. Whenever JDK version is upgraded from one version to another, Run update.bat file as follow:

    • (64-bit) update.bat 64
  1. Download the Connector Gateway from the Mainframe Connectors Downloads page.

  2. Unzip the ConnectorGateway-releaseVersion.zip file in the temporary directory.

    The following files are extracted:

    • init.xml
    • install.bat
    • update.bat
    • log4j.properties
    • ConnectorGateway.jar
    • ConnectorGateway64.exe
    • log4j-core-2.26.0.jar
    • log4j-api-2.26.0.jar
    • log

  3. Add the bin directory of the Java Development Kit to the system PATH variable.

  4. Edit the init.xml file and set the host and port details for the Mainframe Connector and the listening port for the Connector Gateway in the Server tag.

    For more information on parameters in init.xml file, refer to Example init.xml File.

  5. Run the following to start the Connector Gateway:

    java -jar ConnectorGateway.jar

Upgrading Connector Gateway

To upgrade the Connector Gateway, download and install the upgrade .zip file from the SailPoint Compass Community.

Important

For Connector Gateway versions preceding version ConnectorGateway-Jun-2025, you must recycle the default encryption key if one is currently in use. For more information, refer to Recycling Encryption Keys.

  1. Download the Connector Gateway from the Mainframe Connectors Downloads page.

  2. Unzip the ConnectorGateway-releaseVersion.zip file in the temporary directory.

    The following files are extracted:

    • init.xml
    • install.bat
    • update.bat
    • log4j.properties
    • ConnectorGateway.jar
    • ConnectorGateway64.exe
    • log4j-core-2.24.3.jar
    • log4j-api-2.24.3.jar
    • log

  3. Begin the upgrade process by stopping the Connector Gateway service or Command Line Interface (CLI).

  4. Retain the backup of the old Connector Gateway configuration.
  5. Replace the existing setup files with the new files extracted from the latest download version.

  6. To update the init.xml file from the latest download, refer to the values provided in the init.xml file from the backup configuration you took earlier.

    For more information on parameters in the init.xml file, refer to Example init.xml File.

  7. Start the Connector Gateway service or Command Line Interface (CLI).

  1. Download the Connector Gateway from the Mainframe Connectors Downloads page.

  2. Unzip the ConnectorGateway-releaseVersion.zip file in the temporary directory.

    The following files are extracted:

    • init.xml
    • install.bat
    • update.bat
    • log4j.properties
    • ConnectorGateway.jar
    • ConnectorGateway64.exe
    • log4j-core-2.24.3.jar
    • log4j-api-2.24.3.jar
    • log

  3. Begin the upgrade process by stopping the SailPoint Connector Gateway process.

  4. Retain the backup of the old Connector Gateway configuration.
  5. Replace the existing setup files with the new files extracted from the latest download version.

  6. To update the init.xml file from the latest download, refer to the values provided in the init.xml file from the backup configuration you took earlier.

    For more information on parameters in the init.xml file, refer to Example init.xml File.

  7. Start the SailPoint Connector Gateway process.

Example init.xml File

The following is an example of a typical init.xml file:

<ConnectorGateway>
  <SM>
    <!-- Agent Hostname or IP Address-->
    <hostname>xx.xx.xx.xx</hostname>
    <!-- Agent port number-->
    <port>2980</port>
    <!-- Default value is IBM1047 -->
    <characterSet></characterSet>
    <!-- Flag indicating whether the TLS communication is enabled between CG and Mainframe Agent -->
    <enableCGtoAgentTLS>true</enableCGtoAgentTLS>
    <trustStore>C:\Java\jre1.8.0_144\lib\security\cacerts</trustStore>
  </SM>
  <Server>
    <!-- Connector Gateway port number-->
    <port>2980</port>
    <enableCGtoPE2TLS>true</enableCGtoPE2TLS>
    <keyStore>C:\Users\UserName\Desktop\Certs\keystore.jks</keyStore>
    <keyStorePass>ij2Hn20pTsyGbV9vum4/3w==</keyStorePass>
    <keyPass>ij2Hn20pTsyGbV9vum4/3w==</keyPass>
  </Server>
</ConnectorGateway>

The parameters of the init.xml file are as follows:

SM Entries

Parameter Description
hostname Hostname of the connector.
port (Agent port number) Port number of the connector. This connection requires a read/write port, so be sure that the defined port+1 is reserved for this connection. For example, if the port number in the init.xml file is 2470, ports 2470 and 2471 must be reserved for the connection to the connector.
characterSet The Provisioning Engine encodes all messages from ASCII to EBCDIC using the IBMCharacterSet defined in the application. The Connector Gateway only needs to decode the header message before sending it to the connector. The characterSet value in the Connector Gateway and IBMCharacterSet in the application must match.
Default - IBM1047
agentCertSubject To enable TLS communication between the Connector Gateway and the connector, the Connector Gateway must validate the CN of the certificate subject against this value. Set it using java -jar ConnectorGateway.jar -agentCertSubject <VALUE> - do not set it directly in the init.xml file. The Connector Gateway encrypts the value and stores it in init.xml under the <SM> tag as <agentCertSubject>ENCRYPTED_VALUE</agentCertSubject>. If not specified, the Connector Gateway validates the CN against the FQDN of the machine hosting the connector.
disableHostnameVerification Disables hostname verification. Set <disableHostnameVerification>true</disableHostnameVerification> in init.xml to stop the Connector Gateway from validating the subject name referenced by agentCertSubject.
Default - false
clientProtocols Configures a specific supported TLS version for the Connector Gateway environment, for example <clientProtocols>TLSv1.2</clientProtocols>, which sets the jdk.tls.client.protocols system property. The default value is decided based on the JRE version available on the Connector Gateway and Mainframe environments.
enableFIPS Enables FIPS for the Connector Gateway. Set <enableFIPS>true</enableFIPS> in init.xml to enable. For more information, refer to Enabling FIPS for Connector Gateway.
Default - false
trustStorePassword Truststore password used by the Connector Gateway, for example <trustStorePassword>Encrypted_Value</trustStorePassword>. Applies only when enableFIPS is enabled - the Connector Gateway ignores this value if enableFIPS is disabled.

Server Entries

Parameter Description
port (Connector Gateway port number) Port number of the Connector Gateway. This connection requires a read/write socket on the defined port, so be sure that the port is reserved for this connection. For example, if the listening port under the server entries is 2980, port 2980 must be reserved for the connection to the Connector Gateway.
send_keep_alive_to_all (Optional) By default, the Connector Gateway sends a keep-alive message only over the ACF2 connector and the interception connection channel. To send the keep-alive message to all active SailPoint / connector connections, add <send_keep_alive_to_all>true</send_keep_alive_to_all> to init.xml.
Default - false
disableSSLLogs When TLS and TRACE level logging are enabled at the Connector Gateway, it prints Java's SSL logs - to the console when running from the command line, or to stdout.log in the log directory when running as a Windows service. Add <disableSSLLogs>true</disableSSLLogs> under the <Server> tag to disable SSL logs.
Default - false
encryptionKeyFile Path to a site-specific Encryption Key file used to encrypt sensitive data in init.xml, for example <encryptionKeyFile>C:\FileName</encryptionKeyFile>. The key must be 16, 24, or 32 bytes long and stored in a file accessible to the Connector Gateway with read permissions.
maxActiveTransactions Maximum number of transactions the Connector Gateway handles simultaneously. Add under the <Server> tag, for example <maxActiveTransactions>20</maxActiveTransactions>.
Default - 10

Recycling Encryption Keys

Encryption Keys externalized in a file can be recycled using the -recycleencryptionkey <newKeyFilePath> command.

You can define a site-specific Encryption Key to encrypt the data. Set the new Encryption Key in a file and then provide Connector Gateway with Read access to the file. The Encryption Key length must be 16, 24, or 32 bytes. For more information on the Encryption Key, refer to TLS Communication.

The -recycleEncryptionKey command updates the values for the following attributes in the init.xml file if they are already defined. For more information on the init.xml file, refer to Example init.xml File.

  • keypass
  • keystorepass
  • agentcertsubject
  • truststorepasswordpe2tlsauth
  • pe2certsubject
  • keypasscgtlsauth
  • keystorepasscgtlsauth
  • trustStorePassword
  • encryptionKeyFile

Important

When you upgrade to a new Connector Gateway version, be sure to copy the values from your old init.xml file into the new Connector Gateway version's init.xml file.

Caution

Since the -recycleencryptionkey command updates init.xml, SailPoint strongly recommends that you create a backup of the init.xml file prior to running the command as a precaution.

Recycle the Default Encryption Key

You must recycle your Default Encryption key if your Connector Gateway version is older than ConnectorGateway-Jun-2025. The Default Encryption key used in prior versions won't work with ConnectorGateway-Jun-2025 and subsequent releases.

Use the following command to recycle it:

java -jar ConnectorGateway.jar -recycleEncryptionKey <new_key_file> default

In the command, <new_key_file> is the full file path containing the new encryption key file.

Recycle a Custom Encryption Key

To recycle existing custom keys, use the following command:

java -jar ConnectorGateway.jar -recycleEncryptionKey <new_key_file>

In the command, <new_key_file> is the full file path containing the new encryption key file.

Uninstalling the Connector Gateway

Uninstall the Connector Gateway from Windows or UNIX computer. The process to do so varies depending on your operating system.

  1. Stop the SailPointConnectorGateway_<service name> Windows service.

  2. Run following command from command prompt, to uninstall Connector Gateway installed on 32-bit or 64 bit Java run:

    • (32-bit) ConnectorGateway32.exe //DS//"SailPointConnectorGateway_<service name>"
    • (64-bit) ConnectorGateway64.exe //DS//"SailPointConnectorGateway_<service name>"

  3. Manually remove the installation directory.

  1. Stop the SailPoint Connector Gateway process.
  2. Manually remove the installation directory.

Configuration Parameters for SailPoint

The following table describes the additional configuration parameters that can be used with the REST API (System Configuration and Application Configuration):

Parameter Description
IBMcharacterSet The related character set in SailPoint for the code page used on the Mainframe Connector side, for example <entry key="IBMcharacterSet" value="IBM1047"/>.
Default - IBM1047
disableHotpathForUpdate Disables the hotpath for all Update Account operations, preventing the SailPoint database from updating with Update operation changes from the managed system. When enabled, disableHotpathForChgPwd and disableHotpathForManageAcntOp are ignored, for example <entry key="disableHotpathForUpdate" value="true"/>.
Default - false (hotpath enabled)
disableHotpathForChgPwd Disables the hotpath for Change Password operations only. When disabled, the connector sends the status immediately to improve performance, but the latest connector information is not updated in the SailPoint database, for example <entry key="disableHotpathForChgPwd" value="true"/>.
Default - false (hotpath enabled)
disableHotpathForManageAcntOp Disables the hotpath for Enable, Disable, and Unlock operations, preventing the SailPoint database from updating with those changes from the managed system, for example <entry key="disableHotpathForManageAcntOp" value="true"/>.
Default - false (hotpath enabled)
splAccountAttributes Sets unspecified attributes in the schema that SailPoint expects to send or receive, for example RU_LOCKED and RU_SUSPENDED, using a <Map> of entries such as <entry key="RU_LOCKED" value="false"/>. Since the field maps to locked, this field is not required in the schema.
UserAdminMap Maps the numerical keys of the USER_ADMIN account field to readable values in the Application definition, for example 1 to User, 2 to Auditor, 3 to Administrator, 4 to Both, and 5 to Ignore. Run the aggregation task to view the changes in SailPoint.
When setting the USER_ADMIN field value in SailPoint, enter the value as defined in the map - for example User, not 1.
syncSchema Synchronizes the SailPoint application schema with the Mainframe Connector, for example <entry key="syncSchema" value="true"/>.
Default - true
smReadTimeout Timeout value, in minutes, for messages exchanged between SailPoint and the Mainframe Connector for a transaction, for example <entry key="smReadTimeout" value="10"/>.
Default - 10 minutes
failWhenSkip By default, the Mainframe Connector treats the SKIP return code as a success. Set this to true to treat SKIP as a failure instead, for example <entry key="failWhenSkip" value="false"/>.
failWhenWarn By default, the Mainframe Connector treats the WARN return code as a failure. Set this to true to treat WARN as a success instead, for example <entry key="failWhenWarn" value="true"/>.

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.