# SailPoint RACF Connector Documentation

> RACF 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 do not support wild card characters like asterisks (\*) or spaces.
> - 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 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. Perform account aggregation so that only the accounts starting with configured filter strings to be aggregated.

# Connection Attribute Management

Connection Attribute Management enables you to manage System Privileges and Connection Privileges.

## System Privileges

The `SYSTEM_ACCESS` attribute in the Account schema manages system privileges.

- The Account aggregation fetches `SYSTEM_ACCESS` properties along with other properties of the account. `SYSTEM_ACCESS` manages the following attributes:

  - SPECIAL
  - OPERATIONS
  - AUDITOR
  - ROAUDIT
- `SYSTEM_ACCESS` is a multi-valued entitlement attribute. So, the values SPECIAL, OPERATIONS, AUDITOR, and ROAUDIT are added as an entitlements in the Entitlement Catalog.
- `SYSTEM_ACCESS` supports provisioning operations and certification like any other entitlement attribute.

> [!IMPORTANT]
>
> - If the `SYSTEM_ACCESS` attribute is sent through the provisioning plan along with the `USER_ADMIN` and `OPERATIONS` attributes then `USER_ADMIN` and `OPERATIONS` are ignored.
> - `SYSTEM_ACCESS` attribute creation is not supported in SailPoint. Only the `SYSTEM_ACCESS` attribute with values SPECIAL, OPERATIONS, AUDITOR, and ROAUDIT are supported.

### Configurations for System Privileges

1. Add `SYSTEM_ACCESS` as a string attribute in the Account schema by selecting the following in Advanced properties:

   - Entitlement
   - Multi-Value
   - Managed
2. Enable **Manage Privileged Access** so the connector manages Connection privileges.
3. Apply the PRT version FSD0134 or later on the SailPoint Connector for RACF version 4.0.01.

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

## Connection Privileges

Connection Privileges indicates the privilege(s) an account has on a RACF group.

During group aggregation, SailPoint creates three additional groups for each group that it receives from RACF system. The three additional groups are named in the following format:

```text
<Connection Privileges>.<Group Name>
```

where:

`<Connecton Privileges>` can be:

- `SPECIAL`
- `OPERATIONS`
- `AUDITOR`

`<Group Name>` is the name of the group that SailPoint receives from RACF system.

For example, if SailPoint receives a Group named `ENGG` from RACF during group aggregation, four groups are added:

- `ENGG`
- `SPECIAL.ENGG`
- `OPERATIONS.ENGG`
- `AUDITOR.ENGG`

These four groups can be requested and certified like any other entitlements.

The connection privileges can be managed with add and remove entitlement operations. For example, if an add access request is sent for an account for a user named John to connect to `SPECIAL.ENGG`, then John's account with the ENGG group will have SPECIAL privileges on RACF.

SailPoint displays the following connections on John's account:

- `ENGG`
- `SPECIAL.ENGG`

### Configurations for Connection Privileges

The connection privileges can be enabled by adding the following attribute using the REST API:

```text
POST <url>/api/source/update/<sourceID>
```

where:

- `<url>` is the URL for the customer's SailPoint instance
- `<sourceID>` is the Source ID (number) obtained through the UI

In the body of the POST, set form-data values as follows:

- `key` - key name of the entry. Use `connector_CONNECTION_ATTRIBUTES`.
- `value` - true

> [!NOTE]
>
> Delete the `OWNER` attribute if it exists in the `splConnectionAttributes` section.

# 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 RACF for Integration

This section describes additional configurations to perform:

## Installing and Configuring Connector Gateway

Download the .zip files for the latest [Connector Gateway](<https://community.sailpoint.com/knowledge/Mainframe-Connectors-Downloads>) release.

The Connector Gateway can be installed on UNIX/Windows computer with network connectivity to SailPoint and the Mainframe 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 the 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 Connector Gateway, the interceptions are no longer stored in file or read from a file. Pending interceptions which were stored in a file by a previous version of the Connector Gateway, or pending interceptions not sent to the Provisioning Engine will be invalid.

  - The Connector Gateway and the Mainframe Connector can be started / stopped in any order.
  - If there is a firewall between the Connector Gateway and the Mainframe Connector, then you must open the port and port +1 that the Mainframe Connector is listening to.

> [!NOTE]
>
> You are only entitled to download components for which you have an active license with SailPoint. The availability of a component for download does not grant you a license to use it. Downloading a component which you do not have an active license for does not entitle you to use it. Please contact your Account Representative or CSM for more information.

### Supported Operating Systems

The Connector Gateway provides support for the following versions:

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

> [!NOTE]
>
> For Linux Support, the distributions and versions of Linux highlighted above are verified, but any currently available and supported distributions and versions of Linux will be supported by SailPoint. Implementers and customers must verify that the distribution and version of Linux of choice is compatible with the version of JDK being used.

### 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 Mainframe 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/racf/va/help/configuring_racf/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/racf/va/help/configuring_racf/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 Multi-Factor Authentication Attribute Management

The SailPoint connector for RACF can update Multi-Factor Authentication (MFA) attributes.

## Prerequisites

- Apply PTFs (FSD0167 and FSD0168) on the agent.
- In the **MFA Out of Band Policy** section of the source UI, configure `MFA.OOBPOLICY`
- In the **Special Account Attributes** section of the source UI, configure `MFA.MAP.<factor-name>.<IBM-factor-name>`

## Supported Features

- Account aggregation
- Get User: Get MFA data
- Create User: Set MFA attributes while creating user
- Update User: Update MFA attributes while updating user
- Add or remove factors assigned to the user
- Add or remove policies assigned to the user

## Account Attributes

To manage MFA attributes, add the attributes in the following table to the account schema. Adding the account attributes in the following table (as applicable) to the provisioning request also enables you to provision MFA attributes for RACF users.

| Account Attribute | Description | Attribute Type |
| --- | --- | --- |
| MFA.ENABLE | Indicates if MFA is enabled for the user. Value: Y/N. | Single-value |
| MFA.PWFALLBACK | Indicates if a user can use a traditional password for authentication when MFA authentication fails. Value: Y/N | Single-value |
| MFA.FACTORS | Factors assigned to the user | Multi-value, Entitlement |
| MFA.POLICIES | Policies assigned to the user | Multi-value, Entitlement |
| MFA.\<factor-name\>.ACTIVE | For each factor, indicates if it is active for the RACF user. Value: Y/N | Single-value |
| MFA.\<factor-name\>.TAG.\<tag-attribute\> | Each factor has its own tag attributes. Each attribute that must be included in the aggregation must be individually added to the account schema. Value: the value of the tag | Single-value |

> [!CAUTION]
>
> Provisioning `MFA.Enable=N` with additional attribute settings is not supported.

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

# Revoking Connections

By default, the RACF connector automatically removes a user's connection when they are disconnected from a group. You can configure the connector to revoke connections instead of removing them.

1. Use SailPoint REST API to update the source:

   ```text
   PATCH {apiUrl}/v3/sources/{sourceId}
   [ 
    {
     "op": "add",
      "path": "/connectorAttributes/updateRevokeAttrOnConnection",
     "value": "Y"
     }
   ]
   ```
2. Add the REVOKED attribute in the splConnectionAttributes:

   ```text
   PATCH {apiUrl}/v3/sources/{sourceId}
   [
    {
     "op": "add",
      "path": "/connectorAttributes/splConnectionAttributes/REVOKED",
     "value": "true"
    }
   ]
   ```

If a user initiates a disconnect operation from a group, the connector will now send a command to revoke the connection's attributes instead of completely removing the connection. For user-to-group connections, if the connection is currently in a revoked state, it will be resumed; otherwise, a new connection will be created.

# Client Authentication: Configurations in 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 the resource as follows:

   `RDEFINE APPL <SAILAPPL> UACC(NONE)`

   where `SAILAPPL` is the APPL resource name assigned to the Mainframe Connector
2. Permit administrator read access to the following resource:

   `PERMIT <SAILAPPL> CLASS(APPL) ID(<USERID>) ACCESS(READ)`

   where:

   - `SAILAPPL` is the application name defined earlier
   - `USERID` is the RACF Administrator ID allowed to execute transactions on Mainframe Connector
3. Activate the APPL class if not activated earlier:

   `SETROPTS CLASSACT(APPL) RACLIST(APPL)`
4. Refresh the in-storage RACLIST profiles for the APPL class:

   `SETROPTS REFRESH RACLIST(APPL)`

## Parameters in the Mainframe Connector

The Mainframe Connector verifies the administrator credentials with the transaction received from SailPoint before processing the it. 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 `PROTECTED` 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/racf/va/help/configuring_racf/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 Mainframe Connector](<https://documentation.sailpoint.com/connectors/mainframe/racf/va/help/configuring_racf/security_configurations/client_authentication.html#client-authentication-configurations-in-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 HCPT510 | System SSL Security Level: FMID JCPT511 |
    | 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/racf/va/help/configuring_racf/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/racf/va/help/faqs.html>) and [Troubleshooting](<https://documentation.sailpoint.com/connectors/mainframe/racf/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/racf/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/racf/va/help/img/encryption_file_key.png>)](<https://documentation.sailpoint.com/connectors/mainframe/racf/va/help/img/encryption_file_key.png>) [![Encryption key file path in init.xml](<https://documentation.sailpoint.com/connectors/mainframe/racf/va/help/img/cg.png>)](<https://documentation.sailpoint.com/connectors/mainframe/racf/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/racf/va/help/img/oneway.png>)](<https://documentation.sailpoint.com/connectors/mainframe/racf/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/racf/va/help/img/admin.jpg>)](<https://documentation.sailpoint.com/connectors/mainframe/racf/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/racf/va/help/img/gateway.png>)](<https://documentation.sailpoint.com/connectors/mainframe/racf/va/help/img/gateway.png>) [![init.xml TLS entries](<https://documentation.sailpoint.com/connectors/mainframe/racf/va/help/img/cgateway.png>)](<https://documentation.sailpoint.com/connectors/mainframe/racf/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/racf/va/help/img/onewaycgauth.png>)](<https://documentation.sailpoint.com/connectors/mainframe/racf/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/racf/va/help/img/restart.png>)](<https://documentation.sailpoint.com/connectors/mainframe/racf/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/racf/va/help/img/enable_mtls.png>)](<https://documentation.sailpoint.com/connectors/mainframe/racf/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/racf/va/help/img/tls1.png>)](<https://documentation.sailpoint.com/connectors/mainframe/racf/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/racf/va/help/img/tls2.png>)](<https://documentation.sailpoint.com/connectors/mainframe/racf/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/racf/va/help/img/tls1.png>)](<https://documentation.sailpoint.com/connectors/mainframe/racf/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/racf/va/help/img/tls2.png>)](<https://documentation.sailpoint.com/connectors/mainframe/racf/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 RACF

To connect SailPoint with RACF, 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

This section contains the information for the Connector Gateway and the RACF Connector Settings that the source uses to connect and interact with the RACF managed system.

### Connector Gateway Settings

Provide the connection details for the Connector Gateway.

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

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 that the Connector Gateway is listening to.
3. (Optional) Enable the **Use TLS** option to use TLS communication between Virtual Appliances and the Connector Gateway. For more information on enabling and configuring the TLS communication, refer to [TLS Communication](<https://documentation.sailpoint.com/connectors/mainframe/racf/va/help/configuring_racf/security_configurations/tls_communication.html>) and [TLS Configuration on Virtual Appliances](<https://documentation.sailpoint.com/connectors/mainframe/racf/va/help/configuring_racf/tls_configuration_on_virtual_appliances.html>).

   - You must configure Connector Gateway. For more information, refer to [Installing and Configuring Connector Gateway](<https://documentation.sailpoint.com/connectors/mainframe/racf/va/help/configuring_racf/index.html#installing-and-configuring-connector-gateway>).
   - Configure AT-TLS on the machine where the RACF Connector is installed. For more information, refer to [Implementing AT-TLS Policy for Mainframe Connector Communication](<https://documentation.sailpoint.com/connectors/mainframe/racf/va/help/configuring_racf/security_configurations/tls_communication.html#implementing-at-tls-policy-for-mainframe-connector-communication>).
4. Enable the **Disable Hostname Verification** option to disable the hostname verification during RACF Communication over TLS.
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 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.

### RACF Connector Settings

Enter the authentication information for the RACF source.

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

To successfully connect with RACF System, provide the details of the following parameters:

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

## Aggregation Settings

Configure the filters the 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/racf/va/help/img/racf_s_agg.png>)](<https://documentation.sailpoint.com/connectors/mainframe/racf/va/help/img/racf_s_agg.png>)

1. To manage SPECIAL, OPERATIONS, and AUDITOR permission to RACF groups, enable **Manage Privileged Access**.
2. (Optional) In the **Start Filter Condition for Accounts** field, enter the statements used to filter the aggregated account information.
3. Select **Save**.

## Multi-Factor Authentication Settings

This section contains information that the connector uses to manage Multi-Factor Authentication (MFA) configurations.

> [!NOTE]
>
> SailPoint recommends that you do not update MFA attributes with non-MFA attributes in a single request.

> [!NOTE]
>
> **Screenshot**
>
> [![Multi-Factor Authentication Settings](<https://documentation.sailpoint.com/connectors/mainframe/racf/va/help/img/racf_s_mfa.png>)](<https://documentation.sailpoint.com/connectors/mainframe/racf/va/help/img/racf_s_mfa.png>)

1. Under the **MFA Out of Band Policy** section select **Add Another** to create a new policy. You can create a list of policies to add to a user with the corresponding factor associated with the user.
2. To manage the MFA data, add the list of **Special Account Attributes** in the following format:

   ```text
   MFA.MAP.<factor-name>.<IBM-factor-name>
   ```

   Always set this value to `false`.

   For example, you can enter `MFA.MAP.RSA_SecureID.AZFSIDP1`, where `AZFSID` is the original factor name of IBM in `AZFxxxxx` format to a readable free text name describing the factor, such as `RSA_SecureID`.
3. 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?

> [!NOTE]
>
> **Screenshot**
>
> [![Communication diagram for Mainframe Connectors in SailPoint](<https://documentation.sailpoint.com/connectors/mainframe/racf/va/help/img/faq_mf_idn.png>)](<https://documentation.sailpoint.com/connectors/mainframe/racf/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:

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

```text
<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]
>
> - - 16 bytes - C38A9B8CCAF37167
>   - 24 bytes - C38A9B8CCAF371673017B17D
>   - 32 bytes - C38A9B8CCAF371673017B17D0AAE8396
>
>   The key length should be 16, 24, or 32 bytes. For example:
>
>   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 the Connector Gateway](<https://documentation.sailpoint.com/connectors/mainframe/racf/va/help/configuring_racf/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 RACF

Connecting SailPoint to your Resource Access Control Facility (RACF) source allows you to configure the RACF-managed system. The system can aggregate, provision, and monitor RACF activities to update SailPoint 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 RACF source supports the following features:

- Create, update and delete RACF User Profiles
- Manage RACF Group Profiles related to RACF User Profiles
- Change the passwords or passphrases for RACF User Profiles
- Enable or disable RACF Users
- Revoke connections instead of removing them. For more information, refer to [Revoking Connections](<https://documentation.sailpoint.com/connectors/mainframe/racf/va/help/configuring_racf/revoking_connections.html>).
- Aggregate and provision RACF custom fields
- Differentiate between suspended users and locked users if provided an incorrect password or passphrase
- Support for resource aggregation and provisioning as additional group schema, and requesting permissions for accounts and groups.
- Management of Multi-Factor Authentication (MFA) attributes. For more information, refer to [Support for Multi-Factor Authentication Attribute Management](<https://documentation.sailpoint.com/connectors/mainframe/racf/va/help/configuring_racf/mfa_attribute_management.html>).
- Connection Attribute management. For more information, refer to [Connection Attribute Management](<https://documentation.sailpoint.com/connectors/mainframe/racf/va/help/configuring_racf/connection_attribute_management.html>).
- TLS Support. For more information on implementing support for TLS 1.2, refer to [TLS Communication](<https://documentation.sailpoint.com/connectors/mainframe/racf/va/help/configuring_racf/security_configurations/tls_communication.html>).
- Configure a filter for account aggregation. For more information, refer to [Support for Account Aggregation Filter](<https://documentation.sailpoint.com/connectors/mainframe/racf/va/help/configuring_racf/account_aggregation_filter.html>).
- Group hierarchy for the **SUBGROUP** attribute of a **GROUP** object on the RACF managed system
- 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/racf/va/help/configuring_racf/prefix_value.html>).

The details of supported features are:

| Features | Users |
| --- | --- |
| Create | ✔ |
| Aggregate | ✔ |
| Password Management | ✔ |
| Group Entitlements (Read, Request, Revoke) | ✔ Groups |

### Group Entitlements

Group Entitlements are entitlement types for which SailPoint provides the ability to aggregate additional details from the managed system. These objects have a separate schema-defining list of attributes. The aggregation task fetches the attributes as additional details when aggregation is run for that Group Entitlement type.

| Features | Groups |
| --- | --- |
| Aggregation | ✔ |
| Read Group hierarchy | ✔ |

### Password Management

If Password Management is enabled for your organization, you can change the password for a user of the source. After enabling password management on the source, be aware of the following:

- The password policy defined in SailPoint applies to accounts on this source.
- If you change the password for an application connected to this source, the change will automatically be made to the source itself.

For more information on configuring password management, refer to [Password Management Overview](<https://documentation.sailpoint.com/saas/help/pwd/index.html>).

## Supported Managed Systems

The RACF source 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 RACF connector must also be installed on platform z890 or z990 and the processor should be at driver level 55 or above in order to support the ASN-and-LX-reuse facility.

## 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 RACF Version 4.0.01. Refer to [Mainframe E-Fixes](<https://community.sailpoint.com/knowledge/Release-Notes-for-Mainframe-E-Fixes>).
- Install and configure the SailPoint Connector Gateway. For more information, refer to [Installing and Configuring Connector Gateway](<https://documentation.sailpoint.com/connectors/mainframe/racf/va/help/configuring_racf/index.html#installing-and-configuring-connector-gateway>).

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 |

## Required Permissions

The service account configured for SailPoint in the RACF source must have the SPECIAL attribute to provision all RACF entries. To limit the scope of the service account, the group-SPECIAL attribute may be set to the user's connection to the group as needed. Aggregations and SYNC (GET) operations are done under the control of the CTSACS STC user.

> [!NOTE]
>
> Protected users don't need `Special` or `Auditor` privileges for account or group aggregation. Protected users may be used only if `ALLOW_ADMIN_WITHOUT_PSWD` is set to `Y` in RSSPARM.

To add the SPECIAL attribute to the RACF user (administrator) use the following command:

```text
ALU 'userid' SPECIAL
```

To add the group-SPECIAL attribute to the RACF user (administrator) for a specific group, use the following command:

```text
CONNECT 'userid' GROUP(<group_name>) SPECIAL
```

# Provisioning

The RACF connector supports provisioning, allowing you to create and manage accounts and entitlements in RACF 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

The following generators create the required information while creating an editable RACF account:

| Account Attribute | Generator | Description |
| --- | --- | --- |
| USER\_ID | Generator | The User ID as taken from the profile name |
| password | Generator | The password for RACF |
| UG\_DEF | Disable | Default group of the user. You can write rules or set a static value for this attribute. Alternatively the source can generate it for you. |
| 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.OPCLASS | Disable | Classes assigned to this operator to which BMS messages are to be routed (CICS segment). These classes are in the range of 1 to 24. |
| CICS.OPPRTY | Disable | Priority of the operator that CICS segment uses when it determines the task priority |
| CICS.TIMEOUT | Disable | The time, in hours and minutes, that the operator is allowed to be idle before being signed off a CICS segment. |
| CICS.XRFSOFF | Disable | (FORCE) means that the user is signed off by CICS when an XRF (extended recovery facility) takeover occurs in a 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 datasets in TSO segment. |
| TSO.HOLDCLASS | Disable | Default hold class for a user in a TSO segment |
| TSO.JOBCLASS | Disable | Default job class for a user in a TSO segment |
| TSO.MAXSIZE | Disable | Maximum region size a user can request at logon to a TSO segment |
| TSO.MSGCLASS | Disable | Default message class for a user in a TSO segment |
| TSO.PROC | Disable | Default logon procedure name when logging on through the 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 | The time limit (in seconds) for processes that were created by `rlogind`, `telnetd`, and other daemons - OMVS segment |
| 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 |

> [!NOTE]
>
> - `USER_ID`, `password`, and `UG_DEF` are mandatory attributes.
> - The RACF source retries every account provisioning operation for all the configured retryable errors.

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

### Default Account Attributes

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

Following are the list of account attributes:

| Attribute Name | Description |
| --- | --- |
| USER\_ID | User's RACF ID |
| UG\_DEF | User's default group |
| groups | List of groups this user belongs to |
| SYSTEM\_ACCESS | SPECIAL, OPERATIONS, AUDITOR, or ROAUDIT privileges at system level |
| RESTRICTED | Global access checking is bypassed |
| AUTHORITY | Group authority level for user in the default group (USE / CREATE / CONNECT / JOIN) |
| ADSP | Permanent tape and `DASD` datasets created by the user are protected by discrete profiles |
| CATEGORY | User access to resources is additionally protected by the security categories |
| CLAUTH | Classes in which the user can define profiles |
| DATA | Installation-defined data |
| GRPACC | Group data sets protected by `DATASET` profiles defined by this user are automatically accessible to other users in the group |
| INTERVAL | Number of days during which a user's password and password phrase (if set) remain valid |
| MODEL | Discrete dataset profile name used as a model when new dataset profiles are created that have `USER_ID` as the high-level qualifier |
| NAME | Username associated with the `USER_ID` |
| LANGUAGE.PRIMARY | Primary language of user |
| LANGUAGE.SECONDARY | Secondary language of user |
| OIDCARD | User must supply an operator identification card when logging onto the system |
| OPERATIONS | User has authorization to do maintenance operations on all RACF-protected resources |
| OWNER | Owner of the user or owner group |
| RESUME\_DATE | Starting date when user will be allowed to access the system again |
| REVOKE\_DATE | Starting date when user will be disallowed to access the system |
| SECLABEL | Default security label |
| SECLEVEL | User's security level |
| UAUDIT | RACF logs most events and changed done by the user |
| WHEN.DAYS | Days of the week when the user is allowed to access the system from a terminal |
| WHEN.TIME | Hours in the day when the user is allowed to access the system from a terminal |
| INFO.INTERVAL | Number of days during which a user's password and password phrase (if set) remain valid |
| INFO.CREATE\_DATE | Date when user was defined to RACF |
| INFO.LAST\_LOGIN\_DATE | Last date user login to system |
| INFO.LAST\_LOGIN\_TIME | Last time in `INFO.LAST_LOGIN_DATE` when user logged in to the system |
| INFO.PASSCHG\_DATE | Last date user changed their password |
| INFO.UNKNOWNCAT | Security level unknown category |
| RACF\_REVOKE\_REASON | Revoke reason of account |

#### CICS Segment Attributes

| Attribute Name | Description |
| --- | --- |
| CICS.OPIDENT | Operator ID for use by BMS (basic mapping support) |
| CICS.OPCLASS | Classes assigned to this operator to which BMS messages are to be routed |
| CICS.OPPRTY | Priority of the operator |
| CICS.TIMEOUT | Time, in hours and minutes, that the operator is allowed to be idle before being signed off |
| CICS.XRFSOFF | FORCE means that the user is signed off by CICS when an XRF takeover occurs |

#### DFP Segment Attributes

| Attribute Name | Description |
| --- | --- |
| DFP.DATAAPPL | DFP data application identifier |
| DFP.DATACLAS | Default data class |
| DFP.MGMTCLAS | Default management class |
| DFP.STORCLAS | Default storage class |

#### TSO Segment Attributes

| Attribute Name | Description |
| --- | --- |
| TSO.ACCTNUM | Default TSO account number when logging on |
| TSO.COMMAND | Command run during TSO LOGON |
| TSO.DEST | Default destination to which the system routes dynamically-allocated SYSOUT data sets |
| TSO.HOLDCLASS | Default hold class |
| TSO.JOBCLASS | Default job class |
| TSO.MAXSIZE | Maximum region size the user can request at logon |
| TSO.MSGCLASS | Default message class |
| TSO.PROC | Default logon procedure name when logging on through TSO LOGON panel |
| TSO.SECLABEL | Security label entered or used during TSO LOGON |
| TSO.SIZE | Default or requested region size during TSO LOGON |
| TSO.SYSOUTCLASS | Default SYSOUT class |
| TSO.UNIT | Default name of a device or group of devices that a procedure uses for allocations |
| TSO.USERDATA | Optional installation data defined for the user |

#### WORKATTR Segment Attributes

| Attribute Name | Description |
| --- | --- |
| WORKATTR.WAACCNT | Account number for APPC processing |
| WORKATTR.WAADDR1 | Additional address line \#1 for SYSOUT delivery |
| WORKATTR.WAADDR2 | Additional address line \#2 for SYSOUT delivery |
| WORKATTR.WAADDR3 | Additional address line \#3 for SYSOUT delivery |
| WORKATTR.WAADDR4 | Additional address line \#4 for SYSOUT delivery |
| WORKATTR.WABLDG | Building that SYSOUT information is to be delivered to |
| WORKATTR.WADEPT | Department that SYSOUT information is to be delivered to |
| WORKATTR.WANAME | User name that SYSOUT information is to be delivered to |
| WORKATTR.WAROOM | Room that SYSOUT information is to be delivered to |

#### OMVS Segment Attributes

| Attribute Name | Description |
| --- | --- |
| OMVS.ASSIZEMAX | RLIMIT\_AS hard limit (maximum) resource value that processes receive when they are dubbed a process |
| OMVS.CPUTIMEMAX | RLIMIT\_CPU hard limit (maximum) resource value that OMVS processes receive when they are dubbed a process |
| OMVS.FILEPROCMAX | Maximum number of files this user is allowed to have concurrently active or open |
| OMVS.HOME | OMVS initial directory path name |
| OMVS.MMAPAREAMAX | Maximum amount of data space storage, in pages, that can be allocated by the user for memory mappings of OMVS files |
| OMVS.PROCUSERMAX | Maximum number of processes this user is allowed to have active at the same time, regardless of how the process became OMVS process |
| OMVS.PROGRAM | First program started when TSO command OMVS is entered or when a batch job is started using the BPXBATCH program |
| OMVS.THREADSMAX | Maximum number of `pthread_create` threads, including those running, queued, and exited but not detached, that this user can have concurrently active |
| OMVS.UID | OMVS User identifier |

#### DCE Segment Attributes

| Attribute Name | Description |
| --- | --- |
| DCE.AUTOLOGIN | Whether OMVS DCE is to log this user into OMVS DCE automatically |
| DCE.DCENAME | DCE principal name defined for this RACF user in the DCE registry |
| DCE.HOMECELL | DCE cell name defined for this RACF user |
| DCE.HOMEUUID | DCE universal unique identifier (UUID) for the cell that this user is defined to |
| DCE.UUID | DCE universal unique identifier (UUID) of the DCE principal defined in DCENAME |

## 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 RACF connector also supports groups. The following attributes must be configured on the managed system and in the SailPoint source schema to manage groups.

The following table lists the group attributes:

| Attribute Name | Description |
| --- | --- |
| GROUP\_ID | RACF ID of the group |
| OWNER | RACF-defined user or group which is the owner of the group |
| UNIVERSAL | Universal group with effectively unlimited number of users who may be connected to it |
| MODEL | A discrete MVS dataset profile which is the model for new data sets of this group |
| INFO.CREATE\_DATE | Date when this group was defined to RACF |
| DATA | Installation-defined data |
| SUBGROUP | List of all groups which this group is their SUPGROUP |
| TERMUACC | During terminal authorization checking, RACF allows any user in the group access to a terminal based on the universal access authority for that terminal. |

#### OMVS Segment Attribute

| Attribute Name | Description |
| --- | --- |
| OMVS.GID | Group identifier |

#### OVM Segment Attribute

| Attribute Name | Description |
| --- | --- |
| OVM.GID | OpenExtensions VM group identifier |

#### DFP Segment Attributes

| Attribute Name | Description |
| --- | --- |
| DFP.DATAAPPL | DFP data application identifier |
| DFP.DATACLAS | Default data class |
| DFP.MGMTCLAS | Default management class |
| DFP.STORCLAS | Default storage class |

#### TME Segment Attribute

| Attribute Name | Description |
| --- | --- |
| TME.ROLES | List of roles that reference a specific 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/>)

## Provisioning of Connection\_Owner fails

**Resolution**: Ensure Connection\_Owner is the group owners name; not the group name. Pass the following attribute with the intended group owner's name:

```text
CONNECTION_OWNER
<AttributeRequest name="CONNECTION_OWNER" op="Add" value="<value>"/>
```

## Mainframe connectors don't support special character(s)

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

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

   ```text
   <entry key="IBMcharacterSet" value="IBM1047"/>
   ```
2. Set the value of the `<characterSet>` in the init.xml file of the Mainframe connectors to the same value as that of the `characterSet` in the previous step:

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

## Account/Group data updates incorrectly following an 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 Connector Gateway:

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

   ```text
   log4j.rootLogger = ALL, commonLog
   ```
2. Restart the Connector Gateway.

## If you perform a test connection while an aggregation process is running, the test connection transaction times out

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

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

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

## Transactions take more than 10 minutes to complete

Transactions take an excessive amount of time.

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

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

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

## 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 by the requested target.

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

## Connector Gateway printing Java SSL logs when TLS and TRACE level logging are enabled

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

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

**Resolution** - Disable the SSL logs as follows:

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

  ```text
  <disableSSLLogs>true</disableSSLLogs>
  ```
- Set the `disableSSLLogs` to `true` using the following command:

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

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

  ```text
  <entry key="CGCertSubject" value="http://sailpoint.com"/>
  ```
- `disableHostnameVerification` - This is applicable when the Connector Gateway skips the certificate subject verification.

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

## java.security.cert.CertificateException error in the Connector Gateway log

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

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

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

```text
<agentCertSubject>ENCRYPTED_VALUE</agentCertSubject>
```

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

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

```text
disableHostnameVerification>true</disableHostnameVerification>
```

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

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

```text
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/racf/va/help/configuring_racf/security_configurations/index.html#security-configurations-for-mainframe-integration-components>).

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

**Resolution** - Upgrade to the latest Provisioning Engine.

Or

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

For more information on the `ALLOW_ADMIN_WITHOUT_PSWD` parameter, refer to [Security Configurations for Mainframe Integration Components](<https://documentation.sailpoint.com/connectors/mainframe/racf/va/help/configuring_racf/security_configurations/index.html#security-configurations-for-mainframe-integration-components>).

## CTS1081E User SDDEV123 does not exist

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

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

```text
Timeout Exception
```

**Resolution** - Add the `TLSCommWait` attribute in milliseconds using SailPoint REST API:

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

Use the form-data as follows:

- **Key** - `Connector_TLSCommWait`
- **value** - `100`

## Interception throws Null pointer exception

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

## Peer not authenticated

Test Connection displays the following error when using TLS communication:

```text
peer not authenticated
```

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

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

**Resolution** - 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, you 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.

## Self-change password does not set password with NOEXPIRED

**Issue:** The system does not set the password with NOEXPIRED during a self-change password operation. The user must change the password at first logon.

**Resolution:**

Set `RCF_CHK_PWD_HISTORY` to N in the RSSPARM member of the PARM library.

When you set `RCF_CHK_PWD_HISTORY` to N, the system does not perform a password history check during the change password operation.

## Provisioning fails when Account Attribute Mappings static values include $

**Issue:** Provisioning fails during account creation when an Account Attribute Mappings static value includes the $ character. The system returns this error:

```text
com.sailpoint.seaspray.template.TemplateException: Invalid get reference: <attributeValue> seaspray|line 1, column 2
```

**Resolution:** Wrap the static value in a variable before you pass it.

Use: \#set(v='\<attributeValue\>')v

Example for PADMINS: \#set(v='PADMINS')v

# 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"
    }
]
```