# SailPoint ACF2 Connector Documentation

> ACF2 Connector Documentation

# Documentation

# Support for Account Aggregation Filter

Customize the scope for account aggregation for Mainframe sources using filters. A list of strings can be configured in the **Start Filter Condition for Accounts** field. The connector aggregates all the accounts from Mainframe sources which starts with any of the configured character sets.

> [!NOTE]
>
> - The filter strings don't support wildcard characters like asterisks (\*), spaces, or hyphens (-).
> - Each filter string value must be a prefix of any account and must not be longer than seven characters.

Perform the following steps to configure filters for the Mainframe source in SailPoint:

1. Apply the FSD0135 PTF on the Mainframe Connector.

   > **Note**
   >
   > For more information on the Mainframe E-Fixes and PTF's, refer to [Mainframe Connectors Downloads](<https://community.sailpoint.com/docs/DOC-10344>).
2. In the connector configuration UI, go to **Aggregation Settings \> Start Filter Condition for Accounts**.
3. Set the values for the filter as separate strings in the list. For example, if you want to aggregate the accounts starting with **Emp\_** or **E24** then the filter list must have the following entries:

   - **Emp\_**
   - **E24**
4. Once the filters are configured, perform the **Test Connection** and save the application.
5. Start an account aggregation so that only the accounts starting with the configured filter strings are aggregated.

# Support for X-ROL and X-SGP as Additional Entitlements

The connector supports X-ROL and X-SGP as additional entitlements for ACF2 under certain conditions.

## Prerequisites

- Mainframe Connector E-Fixes:

  - FSD0136, FSD0137, FSD0138
  - For provisioning of X-ROL and X-SGP as an Entitlement: FSD0153

  For more information on the Mainframe E-Fixes and PTF's, refer to [Mainframe E-Fixes](<https://community.sailpoint.com/docs/DOC-10344>).
- ACF2 Version: ACF2 R16

## Supported Features

The following features are supported:

- Account aggregation fetches the following entities:

  - Roles (X-ROL) and Sources (X-SGP) connections
  - Direct and indirect role permissions
  - RoleGroups and SourceGroups
- Request new roles and sources for an account
- Remove existing roles and sources from an account

## Implementing X-ROL and X-SGP

To begin using X-ROL and X-SGP, you need to modify your account schema and provisioning policies. The degree of modification depends if you are implementing X-ROL and X-SGP into a new or existing source.

- If you have an existing source, you will need to manually add all the attributes listed in [Existing Sources](<#existing-sources>) to your account schema.
- If you created a new source, you need to add the Source Schema listed in [Existing Sources](<#existing-sources>) to your account schema and to your provisioning policy.

The Source and Role attributes are required to aggregate other Source and Role attributes. They are also required to populate data for the following read-only attributes:

- AccountRoleDirectPermissions
- AccountRoleIndirectPermissions
- RoleGroups
- SourceGroup

## Existing Sources

For existing ACF2 sources, you must add the `splConnectionAttributes` attribute using the REST API:

`PATCH <url>/beta/sources/<id>`

where:

- `<url>` is the URL for the customer's SailPoint instance
- `<id>` is the ID of the source. For example, 2c9180835d191a86015d28455b4a2329

This can be obtained by calling List Sources.

The body of the PATCH consisting of JSON Patch syntax, representing changes to the source JSON object is as follows:

```json
[{"op" : "add",
"path" : "/connectorAttributes/splConnectionAttributes",
"value" : {
"REFRESH":"false",
"TYPE":"false"
}}]
Content-Type: application/json-patch+json
```

### Managing Roles

#### Account Schema Attributes

| Attributes | Description | Entitlement |
| --- | --- | --- |
| Roles | List of Roles to which this user belongs. | true, managed="true", multi="true" |
| RoleGroups | List of Role groups to which this user belongs. | false, multi="true" |
| AccountRoleDirectPermissions | The direct permissions for account obtained from ROLESET rules. | false, multi="true" |
| AccountRoleIndirectPermissions | The indirect permissions for account obtained through role membership. | false, multi="true" |
| isIncomplete | Indicates that the obtained object data is incomplete. | false |

#### Role Schema Attributes

| Attributes | Description | Entitlement |
| --- | --- | --- |
| RoleName | The name of the Role. | nativeObjectType="role", objectType="role" |
| Description | Description of Role. |  |
| isIncomplete | Indicates that the obtained object data is incomplete. |  |
| IncludeList | List of users included in the Role. | multi="true" |
| ExcludeList | List of users excluded from the Role. This is subset of values from IncludeList. | multi="true" |
| RoleDirectPermissions | The direct permissions of the Role. | multi="true" |

### Managing Sources

#### Account Schema Attributes

| Attributes | Description | Entitlement |
| --- | --- | --- |
| Sources | List of Sources to which this user belongs. | true |
| SourceGroups | List of source groups to which this user belongs. | false |
| isIncomplete | Indicates that the obtained object data is incomplete. | false |

#### Source Schema Attributes

| Attributes | Description | Entitlement |
| --- | --- | --- |
| SourceName | The name of the Source. | nativeObjectType="source", objectType="source" |
| isIncomplete | Indicates that the obtained object data is incomplete. |  |
| IncludeList | List of users included in the Source. | multi="true" |
| ExcludeList | List of users excluded from the Source. This is subset of values from IncludeList. | multi="true" |

# Enabling FIPS for Connector Gateway

FIPS stands for the Federal Information Processing Standards. These standards were developed by the U.S. Federal Government and are mandatory for non-military federal government agencies, contractors, and vendors. They are also used by the private sector on a voluntary basis.

1. In the deployment directory (the folder location where the ConnectorGateway.jar file executes), add the required bouncycastle.jar files.

   Download and add the following latest jar files from [bouncycastle.org](<https://www.bouncycastle.org/>):

   - `bc-fips-*.jar`
   - `bctls-fips-*.jar`
   - `bcpkix-fips-*.jar`
2. In the init.xml file:

   - Set the value of `enableFIPS` to `true`
   - If mutual TLS is enabled between the Connector Gateway and PE2, provide the encrypted value of `trustStorePasswordPE2TLSAuth` using the following command:

     `java -jar ConnectorGateway.jar - trustStorePasswordPE2TLSAuth "password"`
   - Enter the encrypted value of `trustStorePassword`

     To add the encrypted value of `trustStorePassword` to the init.xml file, you must use the following command:

     `java -jar ConnectorGateway.jar -trustStorePassword <Value>`
   - Enter the keystore and `truststore` paths
   - Make any other parameter configurations as required

   > **Note**
   >
   > The keystore and truststore must be in **BCFKS** format. The following is the sample command to create new BCFKS keystore from an existing JKS keystore:
   >
   > `keytool -importkeystore -srckeystore <source_keystore> -srcstoretype JKS -srcstorepass <src keystore password> -destkeystore <new keystore name> -deststoretype BCFKS -deststorepass <new keystore password> -provider org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider -providerpath bc-fips-1.0.2.jar`
   >
   > The following is a sample command to create a new keystore of BCFKS type:
   >
   > `keytool -genkey -alias <anything> -keystore <keystorename>.bcfks -storepass <password> -storetype BCFKS -providername BCFIPS -provider org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider -providerpath bc-fips-1.0.2.jar`
3. Modify the java security file to add the bouncycastle provider to the beginning. Then change the priority of the rest of the providers:

   `security.provider.1=org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider C:HYBRID;ENABLE{ALL}`

   `security.provider.2=org.bouncycastle.jsse.provider.BouncyCastleJsseProvider`
4. Override the classpath to the deployment folder and run the connector gateway .jar file as shown from the deployment folder:

   `java -cp ./* sailpoint.router.common.Main`
5. To view the debug SSL logs, run the Connector Gateway using the following command:

   `java -Djava.security.debug=all -Djavax.net.debug=SSL -cp ./* sailpoint.router.common.Main`

> [!NOTE]
>
> The Connector Gateway may take a while to initialize and synchronize with the Mainframe. If you select **Test Connection** while this is in process, you may get errors from the Mainframe. Wait for Connector Gateway to initialize and connect to Agent before selecting testing the connection.

# 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](<https://community.sailpoint.com/knowledge/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](<https://community.sailpoint.com/knowledge/Connector-Gateway-CG-and-Mainframe-Connectors-FAQ-and>).

> [!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](<https://community.sailpoint.com/knowledge/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](<#example-initxml-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](<https://community.sailpoint.com/knowledge/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](<#example-initxml-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](<#recycling-encryption-keys>).

1. Download the Connector Gateway from the [Mainframe Connectors Downloads](<https://community.sailpoint.com/knowledge/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](<#example-initxml-file>).
7. Start the Connector Gateway service or Command Line Interface (CLI).

1. Download the Connector Gateway from the [Mainframe Connectors Downloads](<https://community.sailpoint.com/knowledge/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](<#example-initxml-file>).
7. Start the SailPoint Connector Gateway process.

### Example init.xml File

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

```xml
<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.<br>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`.<br>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](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/configuring_acf2/enabling_fips.html>).<br>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.<br>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.<br>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>`.<br>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](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/configuring_acf2/security_configurations/tls_communication.html#create-the-encryption-key-file>).

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](<#example-initxml-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"/>`.<br>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"/>`.<br>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"/>`.<br>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"/>`.<br>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.<br>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"/>`.<br>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"/>`.<br>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"/>`. |

# Support for Prefix Value

This connector supports the prefix value to be passed in the plan. It is enhanced to read the 'prependBeforeVal' or 'appendAfterVal' attribute from the attributes map of AttributeRequest in the provisioning plan. It will then prefix/append it to the value of the attribute before passing it to the SailPoint connector for ACF2. This allows the pre/post scripts to access meta data of the provisioning request for each attribute.

The sample provisioning plan is as follows:

```xml
<?xml version='1.0' encoding='UTF-8'?>
  <!DOCTYPE ProvisioningPlan PUBLIC "sailpoint.dtd" "sailpoint.dtd">
   <ProvisioningPlan nativeIdentity="TESTUSR" targetIntegration="Mainframe" trackingId="26a13f3e109d47f8831fb1d9088cf38d">
    <AccountRequest application="Mainframe" nativeIdentity="TESTUSR" op="Modify">
     <AttributeRequest name="VLDRSTCT" op="Add" value="Y"/>
      <AttributeRequest name="SITE" op="Add" value="WEB"/>
       </AccountRequest>
        <AccountRequest application="Mainframe" nativeIdentity="TESTUSR" op="Modify">
         <AttributeRequest name="SourceGroups" op="Add"  value="INSTCLNT()">
          <Attributes>
           <Map>
            <entry key="prependBeforeVal" value="ADD;"/>
             </Map>
              </Attributes>
               </AttributeRequest>
                </AccountRequest>
                 <AccountRequest application="Mainframe" nativeIdentity="TESTUSR" op="Modify">
                   <AttributeRequest name="SourceGroups" op="Add"  value="INSAPALL()">
                 <Attributes>
                <Map>
               <entry key="prependBeforeVal" value="ADD;"/>
              </Map>
             </Attributes>
            </AttributeRequest>
           </AccountRequest>
          <Attributes>
         <Map>
        <entry key="identityRequestId" value="0000043469"/>
       <entry key="requester" value="spadmin"/>
      <entry key="source" value="LCM"/>
     </Map>
    </Attributes>
   <Requesters>
  <Reference class="sailpoint.object.Identity" name="spadmin"/>
 </Requesters>
</ProvisioningPlan>
```

# Client Authentication: Configurations in the Mainframe Connector

SailPoint supports the use of the APPL resource for Mainframe Connector administrator authentication. To configure this, define an **APPL** resource in the Mainframe security product and provide READ access to the administrator(s). This allows transaction executions on the Mainframe connector.

Perform the following steps to define the APPL resource and permissions:

1. Define two additional **SAFDEF** records for the Mainframe Connector **APPL** class:

   ```text
   ACF
   SET CONTROL(GSO)
   INSERT SAFDEF.SPAUTH ID(SPAUTH) REP PROGRAM(CTS****) +
   RACROUTE(REQUEST=AUTH,CLASS=APPL)
   INSERT SAFDEF.SPFAST ID(SPFAST) REP PROGRAM(CTS****)  +
   RACROUTE(REQUEST=FASTAUTH,CLASS=APPL)
   F ACF2,REFRESH(SAFDEF)
   END
   ```
2. Define the Mainframe Connector **APPL** resource to ACF2 and give permission to the ACF2 administrator allowed to execute transactions on the Mainframe Connector.

   ```text
   ACF
   SET RESOURCE(SAF)
   COMPILE * LIST STORE
   $KEY(<SAILAPPL>) TYPE(SAF)
   UID(*) PREVENT
   UID(****************<lid> ) ALLOW
   END
   F ACF2,REBUILD(SAF)
   END
   ```

   where:

   - `SAILAPPL` is the name of the application defined earlier
   - `UID(****************<lid>)` is the LID of the ACF2 Administrator allowed to execute transactions on the Mainframe Connector

## Parameters in the Mainframe Connector

The Mainframe Connector verifies the administrator credentials received with the transaction before processing the transaction. Before processing the transaction, the Mainframe Connector checks if the administrator has read access to the defined APPL resource.

The following RSSPARM parameters are supported in the Mainframe Connector:

| Parameter | Syntax | Default | Description | Notes |
| --- | --- | --- | --- | --- |
| `APPL_NAME` | `RSSNAME APPL_NAME   <SAILAPPL>` | None | Defines the APPL resource, where `<SAILAPPL>` is name of the APPL resource defined in the security product for the Mainframe Connector administrator's authentication. | This parameter is optional. The Mainframe Connector verifies that the administrator requesting a transaction is permitted to use the APPL resource defined by this parameter. |
| `ALLOW_ADMIN_WITHOUT_PSWD` | `RSSNAME ALLOW_ADMIN_WITHOUT_PSWD    Y` | `N` | The `RESTRICTED` parameter determines whether an administrative User ID provided by SailPoint for the Mainframe Connector can be used without providing a password. This parameter must be set to `Y` when either the administrator User ID is defined in the security product without a password, or the mainframe security fix is applied but SailPoint and the Connector Gateway are not upgraded with the security fix. | SailPoint recommends upgrading all the components in the integration and setting `ALLOW_ADMIN_WITHOUT_PSWD` to `N`. |

# Security Configurations for Mainframe Integration Components

This section provides details about the security configurations for communication between SailPoint, the Connector Gateway, and Mainframe Connectors.

There are three components to carry out all the transactions which support Mainframe Integration:

- SailPoint
- Connector Gateway
- Mainframe Connector.

It is crucial to secure the communication channels between these three components. The security mechanisms supported by the Mainframe integration include:

- [TLS Communication](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/configuring_acf2/security_configurations/tls_communication.html>) - TLS for the following communication channels must be enabled to secure the complete solution:

  - TLS between SailPoint and Connector Gateway
  - TLS between Connector Gateway and Mainframe Connector
- [Client Authentication: Configurations in the Mainframe Connector](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/configuring_acf2/security_configurations/client_authentication.html#client-authentication-configurations-in-the-mainframe-connector>) - The Mainframe-based connectors support Client Authentication. Client Authentication verifies every incoming request from SailPoint before executing them. To ensure the authentication process works correctly, the Mainframe Connector expects the client to send credentials with every registered user's request. Before processing a request, the Mainframe Connector first confirms that the user that requested it is authorized to perform transactions.

## Prerequisites

- **Upgrade considerations**

  - Apply FSD0116 on the Mainframe Connector.
  - Install the latest Connector Gateway.

    You can download the latest Connector Gateway at the [Mainframe Connector Downloads](<https://community.sailpoint.com/knowledge/Mainframe-Connectors-Downloads>) page.
- **To enable TLS between SailPoint and Connector Gateway**

  - The **X.509** certificate with CN part of the `<domainName>` must match with FQDN of the system running Connector Gateway.
  - If the certificate is not available, create a CSR (Certificate Signing Request) from the Connector Gateway machine.
  - Submit the CSR to a trusted (internal or third party) CA for signing. Ensure that the CA is on a trusted root CA list of the machine.
- **To enable TLS between Connector Gateway and Mainframe Connector**

  - The following respective components for z/OS versions must be installed for TLS communication:

    | z/OS Version | Cryptographic Services | z/OS Security Level 3 |
    | --- | --- | --- |
    | z/OS 3.2 | System SSL Base: FMID HCPT520 | System SSL Security Level: FMID JCPT521 |
    | z/OS 3.1 | System SSL Base: FMID HCPT460 | System SSL Security Level: FMID JCPT461 |
    | z/OS 2.5 | System SSL Base: FMID HCPT450 | System SSL Security Level: FMID JCPT451 |
    | z/OS 2.4 | System SSL Base: FMID HCPT440 | System SSL Security Level: FMID JCPT441 |
- To utilize available hardware cryptography for performance and advanced features, the task started by CSF must be active in the system where the Mainframe application server is active.
- Configure an AT-TLS policy on Mainframe system. For more information, refer to [Implementing AT-TLS Policy for Mainframe Connector Communication](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/configuring_acf2/security_configurations/tls_communication.html#implementing-at-tls-policy-for-mainframe-connector-communication>).
- The **X.509** certificate with the CN part of the `<domainName>` must match with FQDN of the system running the Mainframe Connector.
- If the certificate is not available, create a CSR (Certificate Signing Request) from the Mainframe machine.
- Submit the CSR to a trusted (internal or third party) CA for signing. Ensure that the CA is on a trusted root CA list of the machine.

> [!NOTE]
>
> **Troubleshooting**
>
> Refer to Connector Gateway (CG) and Mainframe Connectors - [Frequently Asked Questions](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/faqs.html>) and [Troubleshooting](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/troubleshooting/index.html#troubleshooting>) for any issues.

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

> [!NOTE]
>
> The value of `agentCertSubject` parameter must not be set directly in the init.xml file, it must be set only by using the above command.

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](<#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](<https://documentation.sailpoint.com/saas/help/va/index.html>).

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

> [!IMPORTANT]
>
> The following steps apply only to CG 2025 and later. They do not apply to CG versions earlier than Connector Gateway-Jun-2025.

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](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/faqs.html#details-of-encryptionkeyfile>).

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

> [!CAUTION]
>
> If the encryption key file is not provided, the CG uses a hard-coded default key which is not recommended for production environment.

### 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**
   >
   > [![Encryption key file](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/img/encryption_file_key.png>)](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/img/encryption_file_key.png>) [![Encryption key file path in init.xml](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/img/cg.png>)](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/img/cg.png>)

### 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**
   >
   > [![Generate certificate with Common Name](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/img/oneway.png>)](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/img/oneway.png>)
4. Run the following command to export the server certificate (CER):

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

   > **Screenshot**
   >
   > [![Export the server certificate](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/img/admin.jpg>)](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/img/admin.jpg>)

   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**
   >
   > [![init.xml TLS entries](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/img/gateway.png>)](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/img/gateway.png>) [![init.xml TLS entries](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/img/cgateway.png>)](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/img/cgateway.png>)

#### 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**
   >
   > [![Certificate Subject configuration](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/img/onewaycgauth.png>)](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/img/onewaycgauth.png>)
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**
   >
   > [![Restart the Connector Gateway](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/img/restart.png>)](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/img/restart.png>)

#### 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**
   >
   > [![Enable Mutual TLS in the source](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/img/enable_mtls.png>)](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/img/enable_mtls.png>)
6. Go to **Review and Test** and select **Test Connection** to validate the connection.

### Summary of init.xml Elements

| Attribute Name | Description |
| --- | --- |
| `encryptionKeyFile` | Specifies the path to file that contains 16/24/32 - byte encryption key used to encrypt sensitive values in `init.xml`. Required for CG 2025 and later. |
| `keystore / keystorePass / keyPass` | Specify the CG server certificate for TLS. These values are encrypted when generated using `ConnectorGateway.jar`. |
| `enableCGtoPE2TLS` | Enables TLS on CG for connections from SailPoint Connectors. |
| `enablePe2TLSAuth` | Enables client certificate authentication for mutual TLS. |
| `trustStorePE2TLSAuth` | Specifies the path to the truststore (for example, `cacerts`) that contains SailPoint Connector certificates. |
| `PE2CertSubject` | Specifies the Common Name (CN) of the allowed SailPoint Connector certificate. This value is stored in encrypted form in `init.xml`. |

## 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](<#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.

> [!NOTE]
>
> For testing purposes, a local CA can be defined for signing the server certificate.

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

> [!NOTE]
>
> TCPIP must be granted permission to access the key ring to which the Mainframe Connector certificate and the CA certificate are connected.

### Sample File for AT-TLS Policy

```text
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.

> [!NOTE]
>
> The **HandshakeRole ServerWithClientAuth** and **ClientAuthType Required** attributes are commented out in the sample AT-TLS policy provided above. If you are configuring mutual TLS, remove the comment tags same and comment out the **HandshakeRole Server and ClientAuthType PassThru** line instead. These are not needed for mutual TLS.

# TLS Configuration on Virtual Appliances

Enabling a source to communicate with a virtual appliance using a TLS connection encrypts all data sent between the source and the VA.

## Sources That Support TLS

The following sources can be configured to communicate over a TLS connection:

- [Active Directory](<https://documentation.sailpoint.com/connectors/microsoft/active_directory/va/help/index.html>)
- [ACF2](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/index.html>)
- [Top Secret](<https://documentation.sailpoint.com/connectors/mainframe/top_secret/va/help/index.html>)
- [IBM i](<https://documentation.sailpoint.com/connectors/ibm/i/va/help/index.html>)
- [OpenLDAP](<https://documentation.sailpoint.com/connectors/openldap/va/help/index.html>)
- [Oracle Internet Directory](<https://documentation.sailpoint.com/connectors/oracle/internet_directory/va/help/index.html>)
- [RSA](<https://documentation.sailpoint.com/connectors/rsa_authentication_manager/va/help/index.html>)
- [RACF](<https://documentation.sailpoint.com/connectors/mainframe/racf/va/help/index.html>)

## Manually Uploading a Certificate to a Virtual Appliance

### Import a Certificate and Keychain to the Virtual Appliance

> [!IMPORTANT]
>
> When adding a certificate to the virtual appliance (VA), ensure that the certificate you copy is in Privacy-Enhanced Mail (PEM) format.

- Before manually adding a new certificate for the source to your virtual appliance's truststore, ensure the following:
- The virtual appliance (VA) is not connected to the source.
- Connection testing between the source and VA is suspended.
- Scheduled aggregations are temporarily paused, if necessary.
- The source server has been configured for TLS.
- The `va-config-<va_id>.yaml` file has been configured for your virtual appliance.
- You must complete the following steps for every virtual appliance on the virtual appliance cluster connected to the source:

  1. Copy the PEM-encoded certificates to the `/home/sailpoint/certificates` directory. This directory might not be empty because it's where the VA adds any certificates it gets from the source.
  2. Restart the CCG using the following command:

     `sudo systemctl restart ccg`
  3. Watch the `/home/sailpoint/log/ccg-start.log` file. If successful, the import should log messages from the form:

     ```text
     {"@timestamp":"2017-04-21 06:57:12 +0000","level":"INFO","type":"ccg","message":"Checking CCG Sources certificates"}
     {"@timestamp":"2017-04-21 06:57:12 +0000","level":"INFO","type":"ccg","message":"Cert files found: [\"/home/sailpoint/certificates/411818.pem\"]"}
     06:57:12 +0000","level":"INFO","type":"ccg","message":"Importing cert /home/sailpoint/certificates/411818.pem"}
     ```

     > **Note**
     >
     > If you see an error instead of the log messages above, this is an indication that your certificate is in an invalid format. Verify you're using a PEM format for your certificate and then try again.
- Sometimes the export of a certificate may not work properly with the VA. Using the openSSL command to get the certificate is a good way to get the latest certificate.

  1. Use the openSSL command to get the latest certificate:

     1. Run the following command in openSSL:

        `openssl s_client -connect server.example.com:636 > output < /dev/null`
     2. From the command output file, copy the certificate content between `--BEGIN CERTIFICATE--` and `--END CERTIFICATE--`.
     3. Create a new file called `cert.pem` in the `/home/sailpoint/certificates` folder.
     4. Save the copied certificate contents in the new `cert.pem` file.
  2. Restart the CCG using the following command:

     `sudo systemctl restart ccg`

## Using an External Certificate Authority (CA)

### Add the Certificate to the Virtual Appliance

If you're using an external certificate authority, you only have to connect to the VA from the source to import the certificate.

**Prerequisites:**

- The ability to use TLS 1.0 - 1.2
- You have created at least one virtual appliance cluster
- CA root and intermediate certificates are in the Java CAcerts keystore
- The certificate is on the source

**Complete the following steps:**

1. In the source, ensure that the following are true:

   - The **Hostname** for the source matches the hostname in the virtual appliance's configuration.
   - The source is connected to the virtual appliance you configured to use TLS.

   > **Note**
   >
   > If you are using Active Directory with IQService enabled, the Hostname cannot be an IP Address.
2. Change the **Port** to **636**.

   > **Screenshot**
   >
   > [![Change the port to 636](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/img/tls1.png>)](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/img/tls1.png>)
3. If available, select the **Advanced Options** checkbox.
4. In the **Use TLS** field, select the **Enable** checkbox.

   > **Screenshot**
   >
   > [![Enable Use TLS](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/img/tls2.png>)](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/img/tls2.png>)
5. Test the connection.

   > **Note**
   >
   > The source's certificate is auto-imported to the VA.

### Replace an Expired Certificate Issued by an External Certificate Authority

When your certificate has expired, replace it on the source and then reboot your VA.

**Prerequisites**

- Complete the process described in [Add the Certificate to the Virtual Appliance](<#add-the-certificate-to-the-virtual-appliance>).

**Complete the following steps:**

1. Add the new certificate on the source with a new name.
2. Restart the CCG using the following command:

   `sudo systemctl restart ccg`

> [!NOTE]
>
> The source's certificate is auto-imported to the VA.

## Using an Internal Certificate Authority

### Add the Certificate to the Virtual Appliance

If you're using your own certificate authority, you will need to add the root and intermediate certificates to the VA.

> [!NOTE]
>
> This process might also be required if your source is not automatically uploading the certificate from the VA.

**Prerequisites:**

- You have created at least one virtual appliance cluster
- The certificate is on the source

**Complete the following steps:**

1. Import the certificate and the entire key chain (Root and Intermediate Certificates) to the VA as described in [Import a Certificate and Keychain to the Virtual Appliance](<#import-a-certificate-and-keychain-to-the-virtual-appliance>).
2. Restart the CCG using the following command:

   `sudo systemctl restart ccg`
3. In the source, ensure that the following are true:

   - The **Hostname** for the source matches the hostname in the virtual appliance's configuration.
   - The source is connected to the virtual appliance you configured to use TLS.

   > **Note**
   >
   > If you are using Active Directory with IQService enabled, the Hostname cannot be an IP Address.
4. Change the **Port** to **636**.

   > **Screenshot**
   >
   > [![Change the port to 636](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/img/tls1.png>)](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/img/tls1.png>)
5. If available, select the **Advanced Options** checkbox.
6. In the **Use TLS** field, select the **Enable** checkbox.

   > **Screenshot**
   >
   > [![Enable Use TLS](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/img/tls2.png>)](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/img/tls2.png>)
7. Test the connection.

> [!NOTE]
>
> The source's certificate is auto-imported to the VA.

### Replace an Expired Certificate Issued by an Internal Certificate Authority

If you're using an internal CA, you need to add the new certificate on both the source and the VA with a new name.

**Prerequisites:**

- Complete the process described in [Add the Certificate to the Virtual Appliance](<#add-the-certificate-to-the-virtual-appliance_1>)

**Complete the following steps:**

1. Add the new certificate on the source with a new name.
2. Import certificate and entire key chain (Root and Intermediate Certificates) to VA as described in [Import a Certificate and Keychain to the Virtual Appliance](<#import-a-certificate-and-keychain-to-the-virtual-appliance>).
3. Restart the CCG using the following command:

   `sudo systemctl restart ccg`
4. Test the connection.

# Connecting SailPoint and ACF2

Establish a secure connection between SailPoint and the ACF2 system. The information in this section describes how to configure a direct connection.

To connect SailPoint with ACF2, perform the following tasks:

## Adding the Source in SailPoint

To connect to SailPoint, perform the following steps. Once the connection is made, you can configure it to meet your company's needs.

> [!IMPORTANT]
>
> By default, the provisioning feature is **disabled**, and the connector only supports read-only operations. To support provisioning operations, you must manually enable the feature in the source configuration.

**To configure a new source:**

1. Sign in to SailPoint.
2. Go to **Admin \> Connections \> Sources**.
3. Select **Create New**.
4. Search for the connector by entering the name in the search box, and then select **Configure**.
5. In the **Source Name** field, enter a unique and descriptive name for your source. Source names cannot exceed 128 characters.
6. In the **Description** field, provide additional details about the source to help distinguish it from similar sources. This field allows a maximum of 2,000 characters.
7. In the **Source Owner** field, begin typing the name of an owner. Matches appear after you type two or more letters. For more information, refer to [Assigning a Source Owner](<https://documentation.sailpoint.com/saas/help/sources/index.html#assigning-a-source-owner>).
8. Under **Connection Type**, select **Direct Connection** or **Flat File**.

   - **Direct Connection** - A direct connection fetches data from the **Virtual Appliance Cluster** you choose as the application connector for the source. A direct connection configuration allows for real-time updates. For more information about configuring and deploying virtual appliances, refer to the [Virtual Appliance Reference Guide](<https://documentation.sailpoint.com/saas/help/va/index.html>).
   - **Flat File** - Select the flat file if no connector is available, or if another system restricts the connection. This option allows only reading and aggregating data as a generic/delimited application. Provisioning activity is unsupported, and additional configuration pages like connection settings and aggregation settings are unavailable.
9. If you selected **Direct Connection**, in **Virtual Appliance Cluster**, select the virtual appliance cluster that will be used as the application connector for the source.
10. (Optional) Select a governance group to grant its members [source](<https://documentation.sailpoint.com/saas/help/common/users/user_levels.html#source-sub-admin-user-level>) or [role](<https://documentation.sailpoint.com/saas/help/common/users/user_levels.html#role-sub-admin-user-level>) sub-admin level oversight of the source and its access. For more information, refer to [Creating and Managing Governance Groups](<https://documentation.sailpoint.com/saas/help/common/users/governance_groups.html>).
11. If this source represents a primary system containing your organization's personnel records, select the **Authoritative Source** checkbox. For more information, refer to [Creating Identity Profiles](<https://documentation.sailpoint.com/saas/help/setup/identity_profiles.html>).
12. Select **Continue**. The source is created, and you are navigated to the **Source Setup \> Base Configuration** page. Continue to configure your connected source there.

## Base Configuration

Provide the base configuration parameters. Information you entered in the Create New Source dialog is automatically entered into the fields in the Base Configuration page. You can edit this information if necessary.

1. Enter a unique name and description for the source.
2. In the **Source Owner** dropdown list, select the identity that owns this source.

   - To find a source owner, begin entering their name.
3. In the **Virtual Appliance Cluster** dropdown list, select the virtual appliance to use when communicating with your organization's systems. For more information, refer to [SailPoint Virtual Appliances](<https://documentation.sailpoint.com/saas/help/va/index.html>).
4. (Optional) If enabled for your organization, select the **Use a Credential Provider** checkbox to manage the source's authentication using a credential provider.

   > **Note**
   >
   > To add a credential provider, go to **Admin \> Connections \> Credential Providers**. For more information about credential providers, refer to [Credential Providers](<https://documentation.sailpoint.com/connectors/help/credential_providers.html>).
5. Configure the authentication to allow SailPoint to connect to the source. Refer to [Connection Settings](<#connection-settings>) for more information.
6. (Optional) In the **Governance Group for Source Management** dropdown list, select a governance group to associate with this source. For more information about governance groups, refer to [Associating Governance Groups with a Source](<https://documentation.sailpoint.com/saas/help/common/users/governance_groups.html#associating-a-governance-group-with-a-source>).
7. (Optional) Choose whether to enable or disable provisioning for the source. Provisioning is disabled by default.

   - **Enable Provisioning** - Set the toggle to **Enabled** to allow the source to create, update, and deactivate accounts in the connected source system.
   - **Disable Provisioning** - Set the toggle to **Disabled** to disable provisioning for the source. Disabling provisioning will prevent the creation, updating, or deactivating of accounts on this source.
8. Select **Save**.

## Connection Settings

Configure the Connector Gateway, which the connector uses to connect to and interact with the ACF2 managed system.

### Connector Gateway Settings

> [!NOTE]
>
> **Screenshot**
>
> [![Connector Gateway Settings](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/img/acf_conn1.png>)](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/img/acf_conn1.png>)

Provide the following details for Connector Gateway:

1. In the **Host** field, enter the host name or the IP address of the system where the Connector Gateway is installed.
2. In the **Port** field, enter the port which the Connector Gateway is listening to.
3. (Optional) Enable **Use TLS** for communication between Virtual Appliances and Connector Gateway.

   For more information on enabling and configuring the TLS communication, refer to [TLS Communication](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/configuring_acf2/security_configurations/tls_communication.html>) and [TLS Configuration on Virtual Appliances](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/configuring_acf2/tls_configuration_on_virtual_appliances.html>).

   - You must configure the Connector Gateway. For more information, refer to [Installing and Configuring Connector Gateway](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/configuring_acf2/index.html#installing-and-configuring-connector-gateway>).
   - Configure AT-TLS on the machine where the ACF2 Connector is installed. For more information, refer to [Implementing AT-TLS Policy for Mainframe Connector Communication](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/configuring_acf2/security_configurations/tls_communication.html#implementing-at-tls-policy-for-mainframe-connector-communication>).
4. (Optional) Enable the **Disable Hostname Verification** option to disable the hostname verification during ACF2 Communication over TLS. If the **Disable Hostname Verification** is enabled, then the Mainframe Connector doesn't validate the CN of the subject name. By default it is disabled.
5. If the **Disable Hostname Verification** option is not enabled, then provide the Certificate Subject.

   **Certificate Subject** - Provide the Common Name (CN) value of the certificate if the subject of the certificate is not the same as the Fully Qualified Domain Name (FQDN) of the Connector Gateway host. Doing so configures the connector to validate the authenticity of the Connector Gateway before establishing the TLS communication channel.

   The connector checks the CN of the subject of the certificate with the value provided in application configuration as entered in the **Certificate Subject** field.

   If the **Certificate Subject** is not provided, then the connector validates the CN of the subject against the FQDN of the machine hosting the Connector Gateway.

### ACF2 Connector Settings

To connect with ACF2 System:

> [!NOTE]
>
> **Screenshot**
>
> [![ACF2 Connector Settings](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/img/acf_conn2.png>)](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/img/acf_conn2.png>)

1. In the **Connector Name** field, enter the name of the connector as configured in the ACF2 connection configuration.
2. In the **Username** field, enter the name of the service account that authenticates the ACF2 System.
3. (Optional) In the **Password** field, enter the password of the service account.
4. Select **Save**.

## Aggregation Settings

Configure the filters that the ACF2 connector uses to aggregate accounts.

For more information about aggregation, refer to [Loading Account Data](<https://documentation.sailpoint.com/saas/help/accounts/loading_data.html>).

> [!NOTE]
>
> **Screenshot**
>
> [![Aggregation Settings](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/img/acf_agg.png>)](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/img/acf_agg.png>)

1. (Optional) In the **Start Filter Condition for Accounts** field, enter the string to filter the aggregated account information.
2. Select **Save**.

## Review and Test

Perform a test to confirm the connection to SailPoint.

1. Go to **Review and Test**.
2. Confirm that the entries in each field are correct.

   If you note any mistakes, return to the section and make corrections.
3. Select **Test Connection**.

## SailPoint Application Onboarding

SailPoint application onboarding enables you to easily onboard new applications and create sources following the successful onboarding of a discovery source. To use this feature, continue to **Discovered Applications** in the SailPoint user interface.

For more information, refer to [Application Onboarding](<https://documentation.sailpoint.com/saas/help/ai/app_onboarding/index.html>) in the SailPoint SaaS documentation.

# Frequently Asked Questions

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

## What is the Connector Gateway (CG)? Which Mainframe Connectors use the Connector Gateway?

[![Communication diagram for the Mainframe Connectors in SailPoint](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/img/faq_mf_idn.png>)](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/img/faq_mf_idn.png>)

Communication diagram for the Mainframe Connectors in SailPoint

- **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 the CCG running on the VA and is responsible for processing multiple requests received from the SailPoint 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.

## Why is the Connector Gateway needed?

By design, the SailPoint 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.

## Does Connector Gateway support a load balancer?

No. Connector Gateway does not support a load balancer.

## Can the Connector Gateway released for SailPoint be used for IdentityIQ and vice versa?

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

## Details of encryptionKeyFile

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.

## Which version of the Connector Gateway should I use and where can I download it?

SailPoint recommends that you use the latest release of the Connector Gateway with latest the Mainframe Connector bundle release. You can find the link to download the latest the Connector Gateway from [Installing and Configuring Connector Gateway](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/configuring_acf2/index.html#installing-and-configuring-connector-gateway>).

Per the support policy, SailPoint recommends that you upgrade the Connector Gateway to the latest version within 90 days of the upgrade's release.

# Integrating SailPoint with ACF2

Connecting SailPoint to your ACF2 source allows you to configure an ACF2 managed system which can aggregate, provision, and monitor ACF2 activities. SailPoint can update the managed system in real time with user and password changes.

> [!NOTE]
>
> To view the latest features, enhancements, and fixes for all SaaS connectors, refer to the [SaaS Release Notes](<https://community.sailpoint.com/release-notes/saas>) page.

## Supported Features

The ACF2 source supports the following features:

- User aggregation, including connections to ACF2 groups (based on UIDs)
- Group aggregation based on:

  - UIDs in ACF2 rules
  - ACF2 Roles X-ROL
  - ACF2 Sources X-SGP (for DB2 users)
- Create, update and delete ACF2 Users
- Enable and disable ACF2 users
- Connect or disconnect an ACF2 user to a group (based on UID, Role, or Source)
- Change ACF2 users' passwords and passphrases
- Aggregation and provisioning of ACF2 user-defined fields
- TLS support and Mutual TLS

  For more information on implementing TLS 1.2, refer to [TLS Communication](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/configuring_acf2/security_configurations/tls_communication.html>).
- Client authentication

  The ACF2 source supports client authentication, which validates every incoming request from the provisioning engine before executing the request. The source requires the client to send the credentials of a registered user with every request for proper authentication.

  For more information, refer to [Security Configurations for Mainframe Integration Components](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/configuring_acf2/security_configurations/index.html>).
- Customizable account aggregation managed by the ACF2 application.

  For more information, refer to [Support for Account Aggregation Filter](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/configuring_acf2/account_aggregation_filter.html>).
- Support for the prefix value to be passed in the plan. For more information, refer to [Support for Prefix Value](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/configuring_acf2/prefix_value.html>).
- Support for the following ACF2 features:

  - Access requests and remediation of X-ROL and X-SGP Entities for ACF2
  - Entitlement aggregation includes roles (X-ROL) by default
  - Aggregation of sources (X-SGP)

    - Request a new role for an account while removing an existing source from an account
    - Request a new source for an account while removing an existing source from an account (if configured)

### Password Management

You can define and configure the password policy for the Mainframe source you created. For more information, refer to [Managing Password Policies](<https://documentation.sailpoint.com/saas/help/pwd/pwd_policies/pwd_policies.html>).

> [!IMPORTANT]
>
> After making a change on the source, be aware of the following:
>
> - The Password Policy defined in SailPoint applies to the accounts in the source.
> - If you change the password for the source connected to this connector, the change will automatically be made to the source itself.

## Supported Managed Systems

The ACF2 connector provides support for the following versions of IBM z/OS:

- z/OS 3.2
- z/OS 3.1
- z/OS 2.5
- z/OS 2.4

The ACF2 agent must also be installed on the platform z890 / z990 processor at driver level 55 or above in order to support the ASN-and-LX-reuse facility.

> [!NOTE]
>
> The ACF2 connector supports ACF2 release version R16.

## Prerequisites

- Configure at least one virtual appliance cluster and successfully test the connection. For more information, refer to the [Virtual Appliance Reference Guide](<https://documentation.sailpoint.com/saas/help/va/index.html>).
- Configure SailPoint Connector for ACF2 Version 4.0.02.

  For more information on installing the ACF2 Connector, refer to [SailPoint Connector for ACF2 Administration Guide](<https://community.sailpoint.com/knowledge/SailPoint-Connector-for-ACF2-Administration-Guide>) and then apply the recent fixes. For a complete list of the fixes, see [Mainframe E-Fixes](<https://community.sailpoint.com/knowledge/Release-Notes-for-Mainframe-E-Fixes>).

  - ACF2® for z/OS R16 and R15
- Install and configure the SailPoint Connector Gateway. For more information, refer to [Installing and Configuring Connector Gateway](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/configuring_acf2/index.html#installing-and-configuring-connector-gateway>).

## Required Permissions

The ACF2 service account must have ACCOUNT + SECURITY rights.

> [!NOTE]
>
> The service account is the user account which is used to authenticate with the Mainframe System. This is done through the Mainframe Connector and it is referenced as the `Username` attribute on the ACF2 source.

# Provisioning

The ACF2 connector supports provisioning, allowing you to create and manage accounts and entitlements in ACF2 directly from SailPoint.

**Prerequisite:** Your system is configured for provisioning.

When SailPoint provisions new accounts to the source, it uses the attributes on the **Create Account** page as instructions or a template for what to include in the account. This page is also referred to as the *provisioning policy*.

When new access is granted on a source where a user does not already have an account, SailPoint automatically includes account creation in the provisioning. This applies whether provisioning is started from an access request or from an automated role or lifecycle state assignment.

For direct-connect sources, SailPoint automatically creates the account from this configuration. If the source is not configured as a direct-connect source, SailPoint creates and assigns a provisioning task to the source owner and includes the values for the source owner to use in manually creating the account.

> [!IMPORTANT]
>
> This section describes the default **Create Account** configuration. SailPoint recommends that you work with Services to define a provisioning configuration specific to your company's needs. Be sure to verify large changes to the provisioning policy before implementation. Failure to do so might cause provisioning to fail.

## Default Create Account Attributes

When SailPoint provisions new accounts to a ACF2 source, it uses attributes on the Create Profile page as instructions. It can be a template to decide which attributes to include for adding an Account. This page is also referred to as the *provisioning policy*.

> [!IMPORTANT]
>
> This section describes the configuration of the Create Profile section. However, SailPoint recommends that you work with Services to define a Create Profile specific to your company's requirement.

The following generators create the required information while creating a ACF2 account which can be edited:

| Account Attribute | Generator | Description |
| --- | --- | --- |
| USER\_ID | Generator (Create Unique Account ID) | The User ID as taken from the profile name. |
| password | Generator | The password for ACF2. |
| CICS.OPIDENT | Disable | Operator identification for use by BMS (basic mapping support) in CICS segment. This identification for each operator, is 1 to 3 characters long. |
| CICS.TIMEOUT | Disable | Time, in hours and minutes, that the operator is allowed to be idle before being signed off CICS segment. |
| CICS.XRFSOFF | Disable | (FORCE) means that the user is signed off by CICS when an XRF (extended recovery facility) takeover occurs in CICS segment. |
| TSO.ACCTNUM | Disable | Default TSO account number when logging on to TSO segment. |
| TSO.COMMAND | Disable | Command run during TSO logon. |
| TSO.DEST | Disable | Default destination to which the system routes dynamically-allocated SYSOUT data sets in TSO segment. |
| TSO.HOLDCLASS | Disable | Default hold class for a user in TSO segment. |
| TSO.JOBCLASS | Disable | Default job class for a user in TSO segment. |
| TSO.MAZSIZE | Disable | Maximum region size a user can request at logon to TSO segment. |
| TSO.MSGCLASS | Disable | Default message class for a user in TSO segment. |
| TSO.PROC | Disable | Default logon procedure name when logging on through TSO logon panel. |
| TSO.SECLABEL | Disable | Security label entered or used during TSO logon. |
| TSO.SIZE | Disable | Default or requested region size during TSO logon - TSO segment. |
| TSO.SYSOUTCLASS | Disable | Default system out class. |
| TSO.UNIT | Disable | Default name of a device or group of devices that a procedure uses for allocations in TSO segment. |
| TSO.USERDATA | Disable | Optional installation data defined for a user. |
| OMVS.CPUTIMEMAX | Disable | OMVS.CPUTIMEMAX. |
| OMVS.FILEPROCMAX | Disable | Maximum number of files a user is allowed to have concurrently active or open - OMVS segment. |
| OMVS.HOME | Disable | OMVS initial directory path name. |
| OMVS.MMAPAREAMAX | Disable | Maximum amount of data space storage, in pages, that can be allocated by a user for memory mappings of OMVS files - OMVS segment. |
| OMVS.PROCUSERMAX | Disable | Maximum number of processes a user is allowed to have active at the same time, regardless of how the process became OMVS process. |
| OMVS.PROGRAM | Disable | First program started when TSO command OMVS is entered or when a batch job is started using the BPXBATCH program. |
| OMVS.THREADSMAX | Disable | Maximum number of pthread\_create threads, including those running, queued, and exited but not detached, that a user can have concurrently active. |
| OMVS.UID | Disable | User identification in OMVS segment. |

# Schema Reference

The application schema is used to configure the objects returned from a connector.

> [!NOTE]
>
> - The **Account Schema** tab is used to define the attributes for each object type in the application being configured. The schema attributes can be defined as **Entitlement** or **Multi-Valued**. Refer to [Managing Source Account Schemas](<https://documentation.sailpoint.com/saas/help/accounts/schema.html>) for more information.
> - The schema attributes that are not present by [default](<#default-account-schema>) must be defined as strings if not specified.

The ACF2 connector uses the following default correlation and object configurations.

## Default Account Schema

Each source supports a variety of details, or attributes, about each user who has an account, such as their name, email address, manager name, and location.

The set of account attributes each source stores and how they're organized is known as the account's *schema*. To best represent your data, you can configure sources to use an account schema matching the one you use in the external connector. Refer to [Managing Source Account Schemas](<https://documentation.sailpoint.com/saas/help/accounts/schema.html>) for more information.

### Default Account ID

SailPoint requires that certain attributes remain in your configuration. These attributes are referred to as *account IDs*.

> [!CAUTION]
>
> Changing the attribute marked as the account ID after aggregating accounts can result in duplicate accounts being created. To avoid this, either reset the accounts on this source before editing the account ID attribute or edit the account ID attribute before aggregating accounts.
>
> To resolve issues caused by changing account IDs, reconfigure them to their default values.

The following table lists the default account IDs for this connector:

| Account ID | Schema Object Type |
| --- | --- |
| USER\_ID | Account |
| GROUP\_ID | Group |
| RoleName | Roles |
| SourceName | Sources |

### Default Account Attributes

The ACF2 connector supports the following default account schema attributes and customer configurable attributes. The attributes must be defined as strings if not specified.

| Attribute Name | Description |
| --- | --- |
| USER\_ID | ACF2 ID of the user |
| OMVS.ASSIZE | Max address space size - OMVS user profile |
| OMVS.CPUTIME | Max cputime for a dubbed process - OMVS user profile |
| OMVS.FILEPROC | Max files per process - OMVS user profile |
| OMVS.HOME | Defines the pathname of the initial directory |
| OMVS.MMAPAREA | Max-data-space pages-for-HFS-mappings - OMVS user profile |
| OMVS.OMVSPGM | OMVS shell program started when the OMVS command is entered |
| OMVS.PROCUSER | Max number of processes - OMVS user profile |
| OMVS.THREADS | Max number of pthread created threads - OMVS user profile |
| OMVS.UID | User identification - OMVS user profile |
| CICS.OPIDENT | Operator ID - CICS user profile |
| CICS.OPPRTY | Operator priority - CICS user profile |
| CICS.TIMEOUT | Idle time value - CICS user profile |
| CICS.FORCE | Indicates whether the user is signed off (FORCE) or not signed off (NOFORCE) when an XRF takeover occurs. - CICS user profile |
| CICS.OPCLASS | Operator class values - CICS user profile |
| DCE.HOMEUUID | Home cell UUID - DCE user profile |
| REVOKE\_TYPE | Revoke type (SUSPEND, CANCEL, Both) of the user |
| NAME | Name of the user |
| UID | UID pseudo field, concatenation of selected logonid fields |
| UIDX | Multiple values UID |
| SEC\_VIO | Number of cumulative security violations for a user |
| EXPIRE | When the privileges for this logonid will expire |
| SECURITY | User is a security administrator |
| ACCOUNT | User can insert, list, change, and delete logonid records |
| LEADER | User can display and alter certain fields of logonid records for other users |
| AUDIT | User can display the records and parameters of the ACF2 system |
| CONSULT | User can display other logonid records |
| REFRESH | User can issue the /F ACF2,REFRESH operator command to update GSO |
| READALL | User has read and execute access to all data sets at the site |
| TSO | User can log on to TSO |
| STC | Logonid is for use by started tasks only |
| CICS | User can sign on to CICS |
| IMS | User can sign on to IMS |
| MAINT | A logonid can access data sets without CA ACF2 rule validation or logs by means of a specified program executed from a specified library |
| NON\_CNCL | A user with the NON-CNCL privilege defined in their logonid record has full access to any data set or resource despite any security violations that can occur during the access attempt |
| ACC\_DATE | The date of the last system access by this user |
| ACC\_TIME | Time of the last system access by this user (read only) |
| PSWD\_EXP | Password has been manually expired |
| PSWD\_TOD | Date and time when a password was last changed |
| PSWD\_DAT | Date of the last invalid password or password phrase attempt (read only) |
| PSWD\_TIM | Last time a user entered an invalid password (read only) |
| PSWD\_VIO | Number of password violations that occurred on PSWD\_DAT |
| TSOACCT | Default TSO logon account |
| TSOCMDS | TSO command list module name that contains the list of commands that this user is authorized to use |
| TSOFSCRN | User can use the full-screen logon display |
| TSOPERF | Default TSO performance group |
| TSORBA | Mail Index Record Pointer (MIRP) for this user |
| TSORGN | Default TSO region size in kilobytes |
| TSOSIZE | Maximum TSO region size |
| TSOTIME | Default TSO time parameter, which is the CPU time limit (in minutes) associated with the TSO session |
| TSOUNIT | Default TSO unit name |
| TSOPROC | Default TSO procedure name |
| JCL | Indicates the ability to submit batch jobs from TSO and to use SUBMIT, STATUS, CANCEL, and OUTPUT commands |
| ACF2CICS | CA ACF2 CICS security is to be initialized in any CICS region running with this address space logonid |
| CICSCL | CICS operator class |
| CICSID | CICS operator ID |
| CICSPRI | CICS operator priority |
| CICSRSL | CICS resource access key |
| PSWD\_MIX | Current password is case-sensitive |
| NOMAXVIO | Prevents the user violation counter from incrementing and MAXVIO processing from occurring |

## Default Entitlement Attributes

Entitlement attributes define the entitlements, such as groups or roles, that can be assigned to the managed system's user accounts. Refer to [Managing Entitlements](<https://documentation.sailpoint.com/saas/help/access/entitlements.html>) for more information.

> [!CAUTION]
>
> Changing the attribute marked as the Entitlement ID after aggregating accounts or entitlements can result in duplicate entitlements being created, or access profiles and roles breaking. To avoid this, edit the entitlement schema before performing any aggregations.

### Default Group Attributes

The ACF2 connector also supports groups. The following attributes must be configured on the managed system and in the SailPoint source schema to manage groups.

| Attribute Name | Description |
| --- | --- |
| GROUP\_ID | ACF2 ID of the group |
| DESCRIPTION | Description of Group (free text) |
| UIDMASKS | UID mask which defines this Group. All users matching this UID mask belong to this group. |

# Enable Connector Logging

This topic provides the steps needed to enable logging on SailPoint using REST APIs.

> [!NOTE]
>
> This topic only applies to VA-based integrations.

> [!NOTE]
>
> The examples provided might not match your configuration. Use the logging levels and logging classes reference at the bottom of the topic to configure your API responses to match your connector.

This process is broken up into four steps:

1. Identify the Virtual Appliance (VA) cluster on which you want to enable logging.
2. Get the logging configuration for the existing VA cluster.
3. Update the VA cluster to enable logging levels.
4. Observe logging changes to the logging levels.

### Identify the Virtual Appliance Cluster

Select the VA on which you need to enable logging using REST API. If you already know the VA application's `id`, proceed to [Get the Logging Configuration](<#get-the-logging-configuration>).

1. Make the following call to the REST API to return a list of available VA clusters:

   GET /v3/managed-clusters

   The REST API returns a response that looks similar to the following:

   ```json
   [
       {
           "id": "2c9180866166b5b0016167c32ef31a66",
           "name": "Development Cluster",
           "description": "Development Cluster",
           "clientType": "CCG",
           "ccgVersion": "373_535_70.2.0",
           "pinnedConfig": true,
           "logConfiguration": null
       },
       {
           "id": "2c9180846a93ce60016ab29f039944de",
           "name": "Cloud Cluster",
           "description": "Cloud Cluster",
           "clientType": "CCG",
           "ccgVersion": "373_535_70.2.0",
           "pinnedConfig": true,
           "logConfiguration": {
               "clientId": null,
               "durationMinutes": 60,
               "expiration": "2020-12-15T19:13:36.079Z",
               "rootLevel": "DEBUG",
               "logLevels": {
                   "sailpoint.connector.ADLDAPConnector": "DEBUG"
               }
           }
       }
   ]
   ```

   > **Note**
   >
   > The previous example code shows two VA clusters. One VA cluster has a log configuration and the other does not (refer to the `logConfiguration` value in each returned VA cluster). This is because one of the clusters already has logging enabled. This is just an example configuration, and your environment may not have logging enabled on a cluster.
2. Identify the VA cluster that you want to enable logging on by its name or description and record its `id` attribute.

### Get the Logging Configuration

Get your selected VA's cluster logging configuration and identify the values you need to update.

1. Make the following call to the REST API to return the VA cluster's logging configuration. Replace `{id}` with the VA cluster's `id` attribute value recorded earlier.

   GET /v3/managed-clusters/{id}/log-config

   - If the VA doesn't have a logging configuration currently set, it returns `204 No Content` as a response.
   - If the VA has an existing logging configuration, it returns something similar to the following:

     ```json
     {
         "clientId": null,
         "durationMinutes": 60,
         "expiration": "2020-12-15T19:13:36.079Z",
         "rootLevel": "DEBUG",
         "logLevels": {
             "sailpoint.connector.ADLDAPConnector": "DEBUG"
         }
     }
     ```

     You'll need to configure the following information in the response:

     - `durationMinutes` is the number of minutes logging should remain enabled.
     - `rootLevel` is the default level for all logs. For more information, refer to [Logging Levels](<#logging-levels>).
     - `logLevels` is a map object with logging classes as keys and logging levels as values.

       - For keys, refer to [Logging Classes](<#logging-classes>) for commonly used logging classes.
       - For a list of available values, refer to [Logging Levels](<#logging-levels>).

### Update Logging Configuration

Update the VA cluster configuration returned by the REST API to update the logging settings as needed.

1. Make the following call to the REST API to update the VA cluster's logging configuration. Replace `{id}` with the VA cluster's `id` attribute value recorded earlier.

   PUT /v3/managed-clusters/{id}/log-config
2. Submit your configuration changes to the REST API in a JSON body.

   - If the VA cluster did not already have a logging configuration and you received a `204 No Content` response, you can create a new one.
   - If the VA returned a configuration, you can edit it to include the changes.

   The JSON body should be as follows:

   ```json
   {
       "durationMinutes": 60,
       "rootLevel": "DEBUG",
       "logLevels": {
           "sailpoint.connector.ADLDAPConnector": "DEBUG"
       }
   }
   ```

   Consider the following as you edit the JSON:

   - `durationMinutes` is the number of minutes logging should remain enabled.
   - `rootLevel` is the default level for all logs. For more information, refer to [Logging Levels](<#logging-levels>).
   - `logLevels` is a map object with logging classes as keys and logging levels as values.

     - For keys, refer to [Logging Classes](<#logging-classes>) for commonly used logging classes.
     - For a list of available values, refer to [Logging Levels](<#logging-levels>).

   If the update was successful, the REST API should return a response similar to the following:

   ```json
   {
       "clientId": null,
       "durationMinutes": 60,
       "expiration": "2020-12-15T19:13:36.079Z",
       "rootLevel": "DEBUG",
       "logLevels": {
           "sailpoint.connector.ADLDAPConnector": "DEBUG"
       }
   }
   ```

### Observe Logging Changes

Approximately five minutes after you update the configuration, the VA cluster starts generating log files you can review. You can view the log files in **ccg.log**.

### References

The tables in this reference section list information that can be helpful when creating the JSON body you'll use to configure the VA cluster's configuration file.

#### Logging Levels

| Logging Level | Description |
| --- | --- |
| ERROR | Designates error events that might still allow the connector to continue. |
| WARN | Designates potentially harmful situations. |
| INFO | Designates information messages that highlight process at a coarse-grain level. |
| DEBUG | Very verbose. Fine grain logging levels used for development and debugging. |
| TRACE | Most verbose. Finer grain logging levels than debugging. |

#### Logging Classes

| Connector | Logging Class |
| --- | --- |
| Active Directory | sailpoint.connector.ADLDAPConnector sailpoint.connector.LDAPConnector |
| AIX | openconnector.connector.unix.AIXConnector openconnector.connector.unix.UnixConnector |
| Amazon Web Services | logger.aws.name=openconnector.connector.aws logger.aws.level=trace logger.aws.additivity = false logger.aws.appenderRef.rolling.ref = STDOUT |
| Atlassian Suite Cloud | sailpoint.connector.OpenConnectorAdapter openconnector.connector.atlassian.AtlassianConnector |
| Atlassian Data Center | sailpoint.connector.OpenConnectorAdapter openconnector.connector.atlassian.AtlassianDataCenterConnector |
| Microsoft Entra ID | sailpoint.connector.AzureADConnector |
| Box | openconnector.connector.BoxNetConnector sailpoint.connector.OpenConnectorAdapter |
| Cerner | openconnector.connector.CernerConnector sailpoint.connector.OpenConnectorAdapter |
| Delimited File | logger.DelimitedFileConnector.name = sailpoint.connector.DelimitedFileConnector logger.DelimitedFileConnector.level = debug logger.DelimitedFileConnector.additivity = false logger.DelimitedFileConnector.appenderRef.rolling.ref = STDOUT |
| Dropbox | openconnector.connector.DropBoxConnector sailpoint.connector.OpenConnectorAdapter |
| Epic | openconnector.connector.EPICConnector sailpoint.connector.OpenConnectorAdapter |
| GE Centricity | openconnector.connector.GECentricity sailpoint.connector.OpenConnectorAdapter |
| Google Apps / G Suite | openconnector.connector.GoogleAppsDirect sailpoint.connector.OpenConnectorAdapter |
| IBM i | openconnector.connector.IBMiConnector |
| Lotus Domino | sailpoint.connector.LotusDomino |
| JDBC | sailpoint.connector.JDBCConnector |
| Sun One LDAP | sailpoint.connector.LDAPConnector |
| Linux | openconnector.connector.unix.LinuxConnector sailpoint.connector.OpenConnectorAdapter sailpoint.connector.UnixConnector |
| Microsoft Office365 | sailpoint.connector.Office365Connector |
| Microsoft SQL Server | sailpoint.connector.mssql.serviceimpl.MSSQLServerConnectorV2 |
| Okta | logger.openconnector.name = openconnector.connector.okta.OktaConnector logger.openconnector.level = debug logger.openconnector.additivity = false logger.openconnector.appenderRef.rolling.ref = STDOUT |
| Oracle Database | sailpoint.connector.OracleDBConnector sailpoint.connector.JDBCConnector |
| Oracle E-Business | sailpoint.connector.OracleEBSConnector sailpoint.connector.JDBCConnector |
| Oracle Fusion HCM | openconnector.connector.oraclefusionhcm.OracleFusionHCMConnector sailpoint.connector.OpenConnectorAdapter |
| Oracle HCM Cloud | sailpoint.connector.oraclehcmcloud.OracleHCMCloudConnector |
| Oracle HRMS | sailpoint.connector.OracleAppsHRMSConnector sailpoint.connector.JDBCConnector |
| Oracle Netsuite | openconnector.connector.netsuite.NetsuiteConnector |
| PeopleSoft ERP | openconnector.connector.PeopleSoftConnector sailpoint.connector.OpenConnectorAdapter |
| PeopleSoft HRMS | sailpoint.connector.PeopleSoftHRMSConnector |
| RemedyForce | sailpoint.connector.ForceConnector |
| RSA Authentication Manager | openconnector.connector.RSAConnector openconnector.connector.rsa.RSAHTTPClient sailpoint.connector.OpenConnectorAdapter |
| Salesforce | sailpoint.connector.ForceConnector |
| SAP Concur | openconnector.connector.sapconcur.SAPConcurConnector |
| SAP - Direct | sailpoint.connector.SAPConnector sailpoint.connector.SAPInternalConnector |
| SAP GRC | logger.SAPGRCConnector.name = sailpoint.connector.sapgrc logger.SAPGRCConnector.level = debug logger.SAPGRCConnector.additivity = false logger.SAPGRCConnector.appenderRef.rolling.ref = STDOUT |
| SAP HR/HCM | sailpoint.connector.SAPHRInternalConnector |
| SCIM 1.1 | openconnector.connector.SCIMConnector sailpoint.connector.OpenConnectorAdapter |
| SCIM 2.0 | openconnector.connector.scim2.SCIM2Connector sailpoint.connector.OpenConnectorAdapter |
| ServiceNow | openconnector.connector.servicenow.ServiceNowConnector openconnector.connector.servicenow.ServiceNowRestClient sailpoint.connector.OpenConnectorAdapter |
| ServiceNow Service Desk Integration | openconnector.connector.servicedesk.ServiceNowServiceDeskConnector sailpoint.connector.OpenConnectorAdapter |
| Siebel | openconnector.connector.SiebelConnector sailpoint.connector.OpenConnectorAdapter |
| Snowflake | openconnector.connector.snowflake.SnowflakeConnector sailpoint.connector.OpenConnectorAdapter |
| Solaris | openconnector.connector.unix.SolarisConnector openconnector.connector.unix.UnixConnector sailpoint.connector.OpenConnectorAdapter |
| SuccessFactors | sailpoint.connector.SuccessFactorsConnector |
| Sybase | sailpoint.connector.SybaseDirectConnector sailpoint.connector.JDBCConnector |
| Webex | openconnector.connector.Webex sailpoint.connector.OpenConnectorAdapter |
| Workday | openconnector.connector.WorkDay sailpoint.connector.OpenConnectorAdapter |
| Workday Accounts | openconnector.connector.workdayaccounts openconnector.connector.workdayaccounts.WorkdayAccountsConnector sailpoint.connector.OpenConnectorAdapter |
| Web Services | sailpoint.connector.WebServices |
| XML | openconnector.connector.XMLConnector sailpoint.connector.OpenConnectorAdapter |
| Yammer | openconnector.connector.YammerConnector sailpoint.connector.OpenConnectorAdapter |
| Zoom | openconnector.connector.zoom.ZoomConnector sailpoint.connector.OpenConnectorAdapter |

# Troubleshooting

If you encounter any of the following issues or errors, SailPoint recommends that you follow the guidance provided below to resolve the error before contacting SailPoint Support.

For issues or errors that are not addressed in this connector guide, refer to the following resources for troubleshooting information:

- [SailPoint Identity Services Documentation](<https://documentation.sailpoint.com/saas/help/index.html>)
- [SailPoint Support Knowledge Base](<https://support.sailpoint.com/csm?id=kb_view2&amp;kb_id=05ff44289f011200550bf7b6077fcfa3>)
- [SailPoint Developer Community](<https://developer.sailpoint.com/>)

## ACF2 is not provisioning due to a TYPE attribute

When the application has a TYPE attribute for a UID string defined in the schema and `splConnection` attributes, then ACF2 will not provision.

**Resolution** - Remove or Rename TYPE from the UID string as an attribute in its definition.

## A third party monitoring tool (Port Monitoring software) usage and its implications

**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 the init.xml file is 2470). This method creates a valid socket connection.
- **Checking the status of the Connector Gateway** - This method involves the use of two telnet sessions as described below:

  Connect on the defined port +1 and on the defined port 2470, (the port defined in the init.xml file 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, preventing the Connector Gateway from determining 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), and if there are no updates from the Connector Gateway within the time variable X (to be defined locally as it pertains to the environment), then Service. With this the Connector Gateway would be Online.
  - Write a log parser that will validate 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. To accomplish this, you can use Firewalls and Routing to isolate traffic to and from only trusted and intended source machines and services. SailPoint recommends that you test the given alternative methods in your environment using the proper Change Management methodologies listed below:

- Develop
- Test
- Promote to production after proper testing is completed

## Special characters not working in Mainframe Connector passwords

**Resolution** - If any special characters are not working in Mainframe Connectors in passwords, perform the following:

1. Change the character set to **IBM1047** for Mainframe Connectors-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 above step:

   `<characterSet>IBM1047</characterSet>`
3. Restart the Connector Gateway.

## Account/Group data updated incorrectly after aggregation

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

## Enable traces

**Resolution** - On the 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.

## During aggregation if a user performs Test Connection, the Test Connection transaction times out

During aggregation if you perform a Test Connection, the Test Connection transaction times out.

**Resolution** - During aggregation if you perform a Test Connection, the Test Connection transaction will time out because the connector is busy processing the aggregation. To resolve this issue, configure Multiple Transaction Servers on the connector to perform more than one transaction at a time.

> [!NOTE]
>
> You can set two or three multiple-transaction servers to handle more concurrent operations, depending on the load.

## Transactions taking more than 10 minutes

Transactions take an excessive amount of time, usually more than 10 minutes.

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

Set the `smReadTimeout` parameter in **Configuration \> System Configuration** 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.

## During aggregation, records are truncated when data exceeds the buffer limits for one or more entities

**Resolution** - The `FOREVERY MAX_MSG_SIZE 32723` attribute indicates the maximum size of a single object record during aggregation. Any record with a size beyond this limit is truncated during aggregation. The `isIncomplete` attribute must be set to `true` in the properties of such records to indicate the truncation. Default value of the attribute is `20480` while the maximum value can be set to `32723`.

## Custom attributes which start with a hash symbol (\#) are excluded from aggregation

Custom attributes in the ACF2 source which start with a hash symbol (`#`) are not aggregated to SailPoint. For example, the attribute, `#EMPL`, would be excluded from aggregation.

**Resolution** - Configure a second attribute with an `@` symbol instead of a hash symbol (`#`). For example, to aggregate `#EMPL`, create the custom attribute, `@EMPL`.

> [!IMPORTANT]
>
> Provisioning custom attributes requires that the attribute has the hash symbol (`#`) in its name. You need to have both attributes configured to support provisioning and aggregation. So, to provision and aggregate the `#EMPL` attribute in the ACF2 source, you must have two attributes: `#EMPL` and `@EMPL`.

## An error message appears when creating an account with lowercase characters

When a user tries to create an account in ACF2 with lowercase characters, the following error message appears:

`Provisioning account failed for operation Create with error: Identity attribute [USER_ID] was not found.`

**Resolution** - Enter the `USER_ID` in uppercase or add the following code into the Application Debug page:

1. Open the Application Debug page and search for the `PlanInitializerScript` tag.
2. Add the following code for the Create Account operation to convert the `USER_ID` entered in lowercase to uppercase.

   ```text
   {{ if (op == AccountRequest.Operation.Create)
       {
           String userId = req.getNativeIdentity();
               if (userId != null)
                   {
                       req.setNativeIdentity(userId.toUpperCase());
                   }
       }
   }}
   ```

## Handling multiple LPARs under SYSPLEX and JESPLEX

The ACF2 Connector uses ENQ with SYSTEMS in order to protect and coordinate writing to the Queue file and to the ACF2UDB and ACF2GDB files. When this scenario exists, all ENQ refer to the same file names and therefore locking is caused between the two LPARs and between the two JESPLEXs.

**Resolution** - Use one of the following methods to resolve this issue:

1. Use different a STC prefix in the two JESPLEXs. SailPoint recommends doing this before the installation of the connector. If done after installation, changing STC names can be more difficult.
2. Use different file names in both JESPLEXs for Queue, ACF2UDB, and ACF2GDB files.
3. Change the QNAME parameter in the `CTSPARM` member in the PARM library and compile it using the `CTSPARMJ` job in the INSTALL library.
4. Restart the connector.

## Unable to find valid certification path to requested target

The following error message appears when multiple versions of Java are installed on the same computer, and the valid certification path is not found to 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.

## (Code Refactoring) Connector Gateway printing Java SSL logs when TLS and TRACE level logging are enabled

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

- If the Connector Gateway is running as a command line, then logs are printed on the Console
- (Windows only) If the Connector Gateway is running as a service then logs are printed in the `stdout.log` file inside the `log` directory of the Connector Gateway.

**Resolution** - Disable the SSL logs doing one of the following:

- 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` by using the following command:

  `java -jar ConnectorGateway.jar -disableSSLLogs true`

## Connection with the Connector Gateway is interrupted

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 `source`:

- `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"/>`

## Certificate Exception error in the Connector Gateway log

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

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

**Resolution** - If TLS communication is enabled between the Connector Gateway and the Mainframe Connector, then the following entry is must be added under the `SM` tag of the init.xml file:

`<agentCertSubject>ENCRYPTED_VALUE</agentCertSubject>`

The `ENCRYPTED_VALUE` can be achieved by using the encryption key mechanism or by 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>`

## CTS1036E R Application name UNDEFAPL specified an error and transaction ends

While performing a Test Connection or any provisioning operation, 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](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/configuring_acf2/security_configurations/index.html#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 the Mainframe Connector, then restart the Mainframe Connector. For more information on the `ALLOW_ADMIN_WITHOUT_PSWD` parameter, refer to [Security Configurations for Mainframe Integration Components](<https://documentation.sailpoint.com/connectors/mainframe/acf2/va/help/configuring_acf2/security_configurations/index.html#security-configurations-for-mainframe-integration-components>).

## Test Connection or Provisioning Fails with CTS1081E User SDDEV123 Does Not Exist

While performing a Test Connection or any provisioning operation 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.

## Timeout Exception

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`

## ACF2 permissions from Target Aggregation not cleaned up

After adding the `AccountDirectPermissions` and `AccountIndirectPermissions` attributes were added in an update, older permissions aggregated via Target Permission are not getting cleaned up. Additionally, The `accountDirect` and `indirectPermissions` attributes are aggregated using account aggregation. In certification, permissions from Target Aggregation and the same permissions (with format structure changes) were populated. So while deleting such permissions, issues were encountered due to the same permissions but with different format structure.

**Resolution** - Perform the following steps to clean up target permissions:

1. Delete the required target source.
2. Run a refresh so that the target permissions related to the deleted target source will be cleaned up.

## Mainframe tools used to handle x37 abends (such as IBM Tivoli® Allocation Optimizer) prevent the Mainframe connector from initializing

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

> [!NOTE]
>
> If you use IBM Tivoli® Allocation Optimizer for z/OS, should add the SailPoint Mainframe connector to its Exclude list.

## Account attributes are not updated after provisioning

**Issue**: Provisioned account attributes are not updated correctly in SailPoint, even when the provisioning operation completes successfully.

**Resolution**:

1. Set **disableHotpathForUpdate** to **false** on the SailPoint source.
2. Use the Patch Source API to update the configuration.

   When **disableHotpathForUpdate** is set to **true**, provisioning continues to execute on the mainframe, but SailPoint does not use the provisioning response to refresh the account object.

# Timeout Errors and Settings

Timeout errors might occur when SailPoint is waiting for a response from the Virtual Appliance (VA). These errors are applicable to all connectors and tend to occur during the setup of sources or when sources are down.

This document is designed to give specific information that can be used to resolve these errors.

Each timeout attribute has a default time value that is listed in seconds or minutes. Increasing the time value may resolve the error as it will allow for longer communication time between the two systems, thus avoiding the timeout error.

> [!IMPORTANT]
>
> Add the necessary attributes or values before performing the "replace" operation, as missing attributes will cause the operation to fail.

To increase the communication time, increase the value of the appropriate timeout attribute. Then submit the change to the VA using the SailPoint REST API.

> [!NOTE]
>
> For more information on SailPoint's REST APIs, refer to [Best Practices: REST API Authentication](<https://developer.sailpoint.com/docs/api/authentication/>) and [REST API - Update Source (Partial)](<https://developer.sailpoint.com/docs/api/update-source-v-1/>) in the SailPoint Developer Community.

### aggregateTimeout

**Description:** This parameter is set for the aggregation timeout, measured in seconds.

**Resolution:** Increase the `aggregateTimeout` value gradually to optimize aggregation. Start with 180, then increase to 600, 900, and finally 1800. The maximum value is 3600 seconds.

For example:

If your current time value is 180 seconds, update the `aggregateTimeout` attribute as follows:

```json
[
    {
        "op": "replace",
        "path": "/connectorAttributes/aggregateTimeout",
        "value": 600
    }
]
```

### healthCheckTimeout

**Description:** This parameter is set for the test connection and health check timeout.

**Resolution:** The default value is 30 seconds. If the timeout error continues, increase the value in 15 second increments and try again.

For example:

If your current time value is 30 seconds, update the `healthCheckTimeout` attribute as follows:

```json
[
    {
        "op": "replace",
        "path": "/connectorAttributes/healthCheckTimeout",
        "value": 45
    }
]
```

### provisioningTimeout

**Description:** This parameter is set for provisioning timeout.

**Resolution:** Increase the `provisioningTimeout` value gradually to optimize provisioning. Start with 180, then increase to 360, and finally 600. The maximum value is 600 seconds.

For example:

If your current time value is 180 seconds, update the `provisioningTimeout` attribute as follows:

```json
[
    {
        "op": "replace",
        "path": "/connectorAttributes/provisioningTimeout",
        "value": 360
    }
]
```

### timeout

**Description:** This parameter is set for pass-through authentication timeout.

**Resolution:** The default value is 15 seconds. If the timeout error continues, increase this value in 15 second increments and try again.

For example:

If your current time value is 15 seconds, update the `timeout` attribute as follows:

```json
[
    {
        "op": "replace",
        "path": "/connectorAttributes/timeout",
        "value": 30
    }
]
```

### apiTimeout

**Description:** This parameter is set for API time tracking; customers can check it using an external tool.

**Resolution:** The default value is 60 seconds. If the error continues, increase the value by 15 second increments and try again.

For example:

If your current time value is 60 seconds, update the `apiTimeout` attribute as follows:

```json
[
    {
        "op": "replace",
        "path": "/connectorAttributes/apiTimeout",
        "value": "75"
    }
]
```

### timeoutInSeconds

**Description:** This parameter helps prevent the VA from waiting indefinitely for an API response, ensuring efficient handling of API requests.

For example:

If your current time value is 30 seconds, update the `timeoutInSeconds` attribute as follows:

```json
[
    {
        "op": "replace",
        "path": "/connectorAttributes/timeoutInSeconds",
        "value": "15"
    }
]
```