Register Sign in Need help? FAQ SailPoint directory
Help
cancel
Turn on suggestions
Auto-suggest helps you quickly narrow down your search results by suggesting possible matches as you type.
Showing results for 
Show  only  | Search instead for 
Did you mean: 

Mainframe Integration Modules

Mainframe Integration Modules

Starting with IdentityIQ 8.3, connector documentation is available in both online and PDF format. This version of this document is no longer being maintained.

 

 

 

Overview

Mainframe Integration Module provides option to connect and manage entities of different mainframe security applications. It consists of LDAP Mainframe Connectors and Mainframe Connectors.

Following connectors are categorized as LDAP Mainframe Connectors. These connectors use the LDAP interfaces to communicate with z/OS LDAP Server.

  • IdentityIQ for RACF LDAP Mainframe
  • IdentityIQ for Top Secret LDAP Mainframe

For more information on the revision history for LDAP Mainframe Connectors, see Revision History for LDAP Mainframe Connectors.

Following connectors are categorized as Mainframe Connectors. These connectors are installed on Mainframe z/OS and uses Connector Gateway.

  • SailPoint Connector for RACF version 4.0.01
  • SailPoint Connector for CA-ACF2 version 4.0.02
  • SailPoint Connector for CA-TopSecret version 4.0.03

NOTE: The above Mainframe Connectors are compatible with IdentityNow and all supported versions of IdentityIQ.

Supported Application Types for Mainframe Connectors

Mainframe Connector on z/OS executes the transactions received from IdentityIQ/IdentityNow via Connector Gateway and sends response to update the status in IdentityIQ / IdentityNow. Each supported Mainframe System has an associated Mainframe Connector. To service requests for a given Mainframe System, it is associated Mainframe Connector is required. The following table lists the supported Mainframe Systems and it's associated Connector:

Mainframe Systems Application Type for IdentityIQ Source for IdentityNow
RACF RACF - Full RACF
CA ACF2 ACF2 - Full ACF2
CA TopSecret (TSS) TopSecret - Full TopSecret

 

Before creating an application, ensure that the following components are installed and configured:

  1. Connector Gateway: For each Mainframe Connector, a Connector Gateway is required to communicate with the Mainframe System.
    For more information on installation and configuration of Connector Gateway, see Installing and Configuring of Connector Gateway.
  2. Mainframe Connectors: Installed and configured to manage the Mainframe System.
    For more information on individual installations of the connector, see the respective Administration Guide (for RACF, CA-Top Secret and CA-ACF2).

Mainframe Connectors

Communication diagram for Mainframe Connector in IdentityIQ/IdentityNow

image.png

  • Provisioning Engine: Provisioning Engine is part of IdentityIQ and CCG running on VA (in case of IdentityNow) and is responsible for processing the multiple requests received from IdentityIQ / IdentityNow server. Each request (T1,T2,...Tn) maintains its dedicated TCP/IP channel to the Connector Gateway to process respective request. The socket channel once opened would be maintained till the request is completed. The communication between Provisioning Engine, Connector Gateway and Mainframe Connector on z/OS can be secured by enabling TLS encryption.
  • Connector Gateway: The Connector Gateway is an independent process running on a server and is responsible for receiving requests from Provisioning Engine and sending those to Mainframe Connector one after another on a pair of socket channel. The socket channel opened between Connector Gateway and Mainframe Connector on z/OS is persistent TCP/IP channel. When Connector Gateway is started it tries to establish a connection (two socket channels on Mainframe Connector on z/OS port and port+1) with Mainframe Connectors.
  • Mainframe Connector on z/OS: The Mainframe Connector on z/OS as shown in the above figure executes the requests (Aggregation, Provisioning Entitlements and Role Assignments, and Password Management) sent by the Provisioning Engine on the system. It also supports intercepting changes from Mainframe to IdentityIQ via Connector Gateway.

 

Supported Features of RACF, ACF2 and TopSecret Mainframe Connectors

SailPoint IdentityIQ / IdentityNow Mainframe Connectors support the following features:

RACF ACF2 TopSecret
  • Create/Update/Delete RACF User
  • Enable/Disable RACF User
  • Change Password/Phrase of RACF User
  • TLS Support: For more information on implementing the support for TLS 1.2, see Enabling TLS Communication
  • Supports setting the scope for account aggregation for the accounts to be managed by the RACF application. For more information, see Support for Account Aggregation Filter
  • Add/Remove a RACF Group Profile to a RACF User Profile
  • Aggregation and Provisioning of RACF Custom Fields
  • User Aggregation and Group Aggregation
  • Differentiation between suspended user versus locked user (incorrect password/phrase)
  • Support for Connection Attributes. For more information, see Support for Connection Attributes
  • Supports Multi-Factor Authentication. For more information, see Support for Multi-Factor Authentication
  • Create/Update/Delete ACF2 User
  • Enable/Disable ACF2 User
  • Change Password/Phrase of ACF2 User
  • TLS Support: For more information on implementing the support for TLS 1.2, see Enabling TLS Communication.
  • Supports setting the scope for account aggregation for the accounts to be managed by the ACF2 application. For more information, see Support for Account Aggregation Filter.
  • Users Aggregation including connections to ACF2 groups (based on UIDs)
  • Manage Direct and Indirect Permission aggregation. For more information, see Manage Direct and Indirect Permissions with Mainframe Connector for CA-ACF2
  • Connect/Disconnect ACF2 User to a Group (based on UID)
  • Groups (based on UIDs in CA-ACF2 rules) aggregation
  • Aggregation and Provisioning of ACF2 user defined fields
  • Supports the following for ACF2:
    • Access requests and remediation of X-ROL and X-SGP Entities for ACF2.
    • Provisioning of X-ROL and X-SGP as Entitlements for ACF2.

For more information, see Managing of X-ROL and X-SGP Entities for ACF2.
  • Create/Update/Delete TopSecret User
  • Enable/Disable TSS User
  • Change Password/Phrase of TopSecret User
  • TLS Support: For more information on implementing the support for TLS 1.2, see Enabling TLS Communication.
  • Supports setting the scope for account aggregation for the accounts to be managed by the TopSecret application. For more information, see Support for Account Aggregation Filter.
  • User aggregation including connections to TSS profiles/groups
  • Connect/Disconnect TSS User to a Profile/Group
  • Profile/Group Aggregation

Following features of Mainframe Connectors are only applicable for IdentityIQ:

 

Additional Information for Mainframe Connectors

This section describes the additional information related to Mainframe Connectors and provides the details for the following topics:

 

Installing and Configuring of Connector Gateway

What's New for Connector Gateway

A new version of Connector Gateway, ConnectorGateway-Feb-2022 is released.

This ConnectorGateway-Feb-2022 version now supports Java Development Kit 1.11 and 1.17 on all supported platforms for all features. This version also upgrades log4j libraries used in the product to log4j 2.17.1. In addition, this release also addresses few known issues reported for earlier releases of Connector Gateway.

You can download the .zip files for ConnectorGateway-Feb-2022 release, here.

 

Overview

The Connector Gateway can be installed on computer with network connectivity to IdentityIQ / IdentityNow 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 that is included with this release of IdentityIQ / IdentityNow, where releaseVersion is the version of the Connector Gateway.

Before you begin

  • Java Development Kit 1.8, 1.11 or 1.17 (32-bit and 64-bit) is required.
  • If there is a firewall between Connector Gateway and Mainframe Connector, then the port and port +1 on which Mainframe Connector is listening must be opened.

Supported Platforms

  • Versions of Microsoft Windows Server, Linux and zLinux supported by their respective providers.

NOTE:

  • Installation steps for Connector Gateway must be followed only if you want to configure Connector Gateway as a service.
  • The Connector Gateway and Mainframe Connector can be started / stopped in any order.

Installation

For Microsoft Windows

  1. (For IdentityIQ) Download the ConnectorGateway-releaseVersion.zip file from IdentityIQ home directory to a temporary directory.
    (For IdentityNow) Download the ConnectorGateway-releaseVersion.zip file from here.
  2. Unzip the ConnectorGateway-releaseVersion.zip file in the temporary directory.
    The following files are extracted:
    • init.xml
    • install.bat
    • log4j2.properties
    • ConnectorGateway.jar
    • ConnectorGateway32.exe
    • ConnectorGateway64.exe
    • log4j-api-2.17.1.jar
    • log4j-core-2.17.1.jar
    • log
  3. Edit the install.bat file and set JDK_HOME to the root directory of your JDK installation.
  4. Run the following install.bat file, to install Connector Gateway on 32-bit or 64-bit:
    • (32-bit) install.bat 32
    • (64-bit) install.bat 64
      And verify if 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 Mainframe Connector.
      For example, you can use 20 as a value for server entries.
  5. Edit init.xml 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, see Parameters of init.xml File.


    NOTE: Restart Connector Gateway after init.xml file is modified.

    The parameters in 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. User can set one or more parameters at a time.

  6. Start the SailPointConnectorGateway_<service name> service.

For Linux

  1. (For IdentityIQ) Download the ConnectorGateway-releaseVersion.zip file from IdentityIQ home directory to a temporary directory.
    (For IdentityNow) Download the ConnectorGateway-releaseVersion.zip file from here.
  2. Unzip the ConnectorGateway-releaseVersion.zip file in the temporary directory.
    The following files are extracted:
    • init.xml
    • install.bat
    • log4j2.properties
    • ConnectorGateway.jar
    • ConnectorGateway32.exe
    • ConnectorGateway64.exe
    • log4j-api-2.17.1.jar
    • log4j-core-2.17.1.jar
    • log
  3. Add the bin directory of Java Development Kit to the system PATH variable.
  4. Edit init.xml 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, see Parameters of init.xml File.
  5. Run the following to start the Connector Gateway:
    java -jar ConnectorGateway.jar

 

Upgrading Connector Gateway

  1. (For IdentityIQ) Download the ConnectorGateway-releaseVersion.zip file from IdentityIQ home directory to a temporary directory.
    (For IdentityNow) Download the ConnectorGateway-releaseVersion.zip file from here.
  2. Unzip the ConnectorGateway-releaseVersion.zip file in the temporary directory.
    The following files are extracted:
    • init.xml
    • install.bat
    • log4j2.properties
    • ConnectorGateway.jar
    • ConnectorGateway32.exe
    • ConnectorGateway64.exe
    • log4j-api-2.17.1.jar
    • log4j-core-2.17.1.jar
    • log
  3. Perform the following steps to upgrade the Connector Gateway version:

    1. (For Microsoft Windows) Stop the Connector Gateway service or Command Line Interface (CLI).
      (For Linux) Stop the SailPoint Connector Gateway process.

    2. Take back-up of the old Connector Gateway set-up.

    3. Replace the existing set-up files with the new files extracted from the latest download version.

    4. To update init.xml from the latest download, you can refer to the values provided in the init.xml from the old set-up.
      For more information on parameters in init.xml file, see Parameters of init.xml File.

    5. (For Microsoft Windows) Start the Connector Gateway service or Command Line Interface (CLI).
      (For Linux) Start the SailPoint Connector Gateway process.

 

Parameters of init.xml File

The following is a typical sample init.xml file:

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

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

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

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

Parameters Description
For SM entries
hostname Hostname of the Mainframe Connector.
port (Agent port number) Port number of the Mainframe Connector. This connection requires a read/write port, hence ensure that the defined port+1 is reserved for this connection. For example, the port number in the following sample file of init.xml is 2470, so the ports 2470-2471 must be reserved for the connection to the Mainframe Connector.
characterSet Provisioning Engine encodes all the messages from ASCII to EBCDIC by using IBMCharacterSet defined in application.

Connector Gateway needs to decode only the header message before sending it to Mainframe Connector.

The value of characterSet in Connector Gateway and IBMCharacterSet in the application must be same.

Default: IBM1047
agentCertSubject

For TLS communication enabled between Connector Gateway and Mainframe Connector, 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 be set by using the following command only:

java -jar ConnectorGateway.jar -agentCertSubject <VALUE>

For example: java -jar ConnectorGateway.jar -agentCertSubject CertSubject

By running the above command Connector Gateway will encrypt the value and store it in init.xml file under "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 should be set only by using the above command.

If agentCertSubject is not specified then the Connector Gateway would validate the CN of the certificate subject against the FQDN of the machine hosting the Mainframe Connector.
disableHostnameVerification The hostname verification functionality is configurable and can be disabled by setting the value of the disableHostnameVerification parameter to true in the init.xml file as follows:

<disableHostnameVerification>true</disableHostnameVerification>

When set to true, the Connector Gateway would not validate the subject name (in reference to agentCertSubject parameter).

Default value is false.
enableFIPS

Enables FIPS for Connector Gateway. The default value is false. To enable FIPS, the value must be set to true in the init.xml file as follows:
<enableFIPS>true</enableFIPS>

For more information on enabling FIPS, see Enabling FIPS for Connector Gateway.
clientProtocols

When TLS communication is enabled between Connector Gateway and Mainframe Connector, clientProtocols can be configured for specific TLS version among supported versions on the Connector Gateway environment. This parameter provides configurable option in init.xml which eventually sets jdk.tls.client.protocols system property:

<clientProtocols>TLSv1.2</clientProtocols>

Default value is decided based on JRE version available on Connector Gateway and Mainframe environments.
trustStorePassword (Applicable only if enableFIPS is enabled) Provide the truststore password. The encrypted value must be provided in the int.xml file as follows:
<trustStorePassword>Encrypted_Value</trustStorePassword>
For Server entries
port

(Connector Gateway port number) Port number of the Connector Gateway. This connection requires a read/write socket on the port defined, hence ensure that the defined port is reserved for this connection. For example, the listening port number under the server entries in the following sample file of init.xml is 2980, so the port 2980 must be reserved for the connection to the Connector Gateway.
forceAgentConnectionResetTimeout

(For IdentityIQ) If interception communication channel between Connector Gateway and Provisioning Engine is interrupted, then:

1. If transactions, except aggregation, are in progress, the Connector Gateway will wait for specified time (default 10 minutes) to complete all the ongoing transactions.

2. In case aggregation is going on, Connector Gateway will accept new transactions from Provisioning Engine until current aggregation transaction completes.

In case of first scenario, and for the second scenario after aggregation is completed, the Connector Gateway will stop receiving new transactions from the Provisioning Engine. In case of scenario 2 after aggregation is completed, Connector Gateway will wait for the configured timeout to try and complete other ongoing transactions. After that Connector Gateway will forcefully reset connection with Mainframe Connector and all active transactions (if any) will fail.

During this time period if the Provisioning Engine tries to establish new interception channel then the Connector Gateway will ignore this request. This timeout is in minutes and default timeout is 10 minutes and is configurable in init.xml as follows:

<forceAgentConnectionResetTimeout>VALUE</forceAgentConnectionResetTimeout>

For example, you can use 20 as a timeout value in minutes.
cleanCGMemoryTimeout

(For IdentityIQ only) If interception communication channel between Provisioning Engine and Connector Gateway is interrupted, then Connector Gateway stores next interceptions coming from Mainframe Connector in Connector Gateway's queue. Once timeout occurs all queued interception messages would be cleared.

Add this parameter as follows under the <Server> entries of the init.xml file of Connector Gateway:

<cleanCGMemoryTimeout>VALUE</cleanCGMemoryTimeout>

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

By default, the timeout value is 10 minutes.
send_keep_alive_to_all

(Optional) Connector Gateway, by default, sends a keep-alive message only over Mainframe connector and interception connection channel. If user wants Connector Gateway to send the keep-alive message to all the active IdentityIQ / Mainframe Connector connections, add the following parameter to the init.xml file of Connector Gateway:

send_keep_alive_to_all>true</send_keep_alive_to_all>

By default, the value of this parameter is false.
disableSSLLogs

If TLS and TRACE level logging is enabled at Connector Gateway then Connector Gateway prints Java's SSL logs. If Connector Gateway is running as command line then logs would be printed on console and if Connector Gateway is running as service (on windows only) then logs would get printed in stdout.log file inside log directory of Connector Gateway.

To disable SSL logs, add disableSSLLogs parameter in init.xml file of Connector Gateway under <Server> tag. Default value is false.

For example, <disableSSLLogs>true</disableSSLLogs>
encryptionKeyFile

This is used to store the encryption/decryption key. The encryptionKeyFile path must be added in the init.xml file as follows:

<encryptionKeyFile>path</encryptionKeyFile>

For example: <encryptionKeyFile>C:\FileName</encryptionKeyFile>

The key length should be 16, 24 or 32 bytes

NOTE: If encryptionKeyFile is not provided or the length is anything other than the specified bytes then Connector Gateway would encrypt/decrypt sensitive data by using the default key. Ensure you recycle the keys and secure this file by giving proper access control.
maxActiveTransactions

Maximum number of transactions handled by Connector Gateway simultaneously.

Add the maxActiveTransactions parameter in the init.xml file under the <Server> tag as follows:

<maxActiveTransactions>value</maxActiveTransactions>

For example, <maxActiveTransactions>20</maxActiveTransactions>

Default value is 10.
TLSVersion

When TLS communication is enabled between IdentityIQ/IdentityNow and Connector Gateway, TLSVersion can be configured for specific TLS version among supported versions on the Connector Gateway environment:

<TLSVersion>TLSv1.2</TLSVersion>

Default value is decided based on JRE version available on IdentityIQ and ConnectorGateway environments.

 

Uninstalling Connector Gateway

For Microsoft Windows

  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.

For Linux

  1. Stop the SailPoint Connector Gateway process.

  2. Manually remove the installation directory.

 

Configuring IdentityIQ Application / IdentityNow Source for Mainframe Connectors

Configuring the Provisioning Engine involves defining an Application in IdentityIQ / IdentityNow for each of the Mainframe Systems. When creating an Application within IdentityIQ / IdentityNow, the following information is required:

  • Application type: Select the type of application that IdentityIQ / IdentityNow is managing. See the Supported Application Types for Mainframe Connectors for the list of supported applications and their respective application types.
  • Connector Gateway details: Each application that IdentityIQ / IdentityNow is managing must have a dedicated Connector Gateway. When defining an application following of the Connector Gateway attributes are required:

    Attributes Description
    Connector Gateway host Hostname/IP of the computer where the Connector Gateway for the Mainframe System is installed.
    Connector Gateway port Port on which the Connector Gateway is listening.

 

  • Mainframe Connector details: A single Mainframe Connector manages one or more instances of an associated application type. Each instance of the application managed by a Connector requires a separate configuration to create a configuration set unique to that instance of the application. The information below is required to establish this differentiation:
    Note: The values of the attributes referenced below are case sensitive and if provided incorrectly, will cause requests from IdentityIQ / IdentityNow to fail.

    Attributes Description

    Connector Name

    		 Enter the Mainframe Connector name as configured for MSCS Name in Mainframe Connector configuration on Mainframe system. It should be in uppercase.
    Username User account used when authenticating to the Mainframe System through the Mainframe Connector.
    Password

    Password for the user account specified in Username.

    NOTE: Special type of user as authentication user is supported in application configuration for Mainframe Connector). For such type of users defined, password field must be kept blank. The special type of users are as follows:

    - Protected for RACF

    - Restricted for ACF2 and

    - With no Password (NOPW) for CA-Top Secret

    Use TLS

    		 Select this checkbox if the connection is over Transport Layer Security (TLS). For more information, see Enabling TLS Communication.

 

Configuration Parameters for IdentityIQ / IdentityNow

The following table describes the additional configuration parameters for:

  • IdentityIQ Debug page (Application Configuration and Target Aggregation)

OR

  • IdentityNow API (System Configuration and Application Configuration)

 

Parameters Description
IBMcharacterSet

The related character set in IdentityIQ / IdentityNow for code page used on the Mainframe Connector side. Default value is IBM1047. The value can be modified as follows:

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

Disables hotpath for all update account operations. This prevents IdentityIQ / IdentityNow database to be updated with the changes (if any) from the Managed system for all update operations. If this parameter is set to true then disableHotpathForChgPwd and disableHotpathForManageAcntOp are ignored and the hotpath will be disabled. Default value is false (hotpath is enabled).

To disable the hotpath for all update operations, set the value to true as follows:

<entry key="disableHotpathForUpdate" value="true"/>
disableHotpathForChgPwd

Disables hotpath for Change Password operation only. If a hotpath is disabled, the Mainframe Connector executes the query and sends the status immediately to improve the performance. By disabling the hotpath, the latest information from Mainframe Connector is not updated in IdentityIQ / IdentityNow database.

Default value is false (hotpath is enabled).

To disable the hotpath for Change password, set the value to true as follows:

<entry key="disableHotpathForChgPwd" value="true"/>
disableHotpathForManageAcntOp

Disables hotpath for Enable, Disable and Unlock operations. This prevents IdentityIQ / IdentityNow database to be updated with the changes (if any) from the Managed system for Enable, Disable and Unlock operations. Default value is false (hotpath is enabled).
To disable the hotpath for Enable, Disable, and Unlock operations, set the value to true as follows:
<entry key="disableHotpathForManageAcntOp" value="true"/>
useMSAdminDefined

(Applicable only for IdentityIQ) Define Managed System Administrator in provisioning plan which can be used by the Mainframe Connector as a Managed System Administrator when a transaction is initiated. Default vale is N (functionality is disabled). To enable this functionality, set the value to Yes (Y) as:
<entry key=”useMSAdminDefined” value=”Y”/>
disableRefresh

(Applicable only for IdentityIQ) Updates the ACF2 database after any roles or sources provisioning operations.

  • When Refresh is enabled, the ACF2 connector issues F ACF2,NEWXREF,TYPE(ROL) or F ACF2,NEWXREF,TYPE(SGP) modify command to update the ACF2 DB.
  • When Refresh is disabled, the NEWXREF modify command is not issued and the ACF2 DB is not updated. The effect of the provisioning transaction is not reflected in ACF2 until a NEWXREF command is issued manually.

By default, Refresh is enabled. SailPoint recommends to use the default setting of Refresh along with Hotpath enabled. To disable refresh add the following entry in application XML:
<entry key="disableRefresh" value="true"/>
splAccountAttributes

Set the attributes which are not specified in schema but are expected to be sent/received by IdentityIQ / IdentityNow. For example, RU_LOCKED. The field is mapped to be locked, hence this field is not required in schema.

<entry key="splAccountAttributes">
 <value>
 <Map>
 <entry key="RU_LOCKED" value="false"/>
 <entry key="RU_SUSPENDED" value="false"/>
 </Map>
 </value>
</entry>
splConnectionAttributes

Add a attribute in the following tag which is a Account-Group connection attribute on Mainframe Connector. The value can be read for the Account in IdentityIQ / IdentityNow.

<entry key="splConnectionAttributes">
 <value>
 <Map>
 <entry key="CONNECTION_ATTRIBUTE_1" value="false"/>
 <entry key="CONNECTION_ATTRIBUTE_2" value="false"/>
 </Map>
 </value>
</entry>

NOTE: For more information, see Support for Connection Attributes.
UserAdminMap

USER_ADMIN field for account is not in readable format and has values like 1,2,3 and so on. To make it readable a map can be added in Application definition as follows:

<entry key="UserAdminMap">
 <value>
 <Map>
 <entry key="1" value="User"/>
 <entry key="2" value="Auditor"/>
 <entry key="3" value="Administrator"/>
 <entry key="4" value="Both"/>
 <entry key="5" value="Ignore"/>
 </Map>
 </value>
</entry>

Run the aggregation task to view the changes in IdentityIQ / IdentityNow.

Note: While setting the value of USER_ADMIN field from IdentityIQ / IdentityNow, user must enter the value as defined in the MAP. For example, to set USER_ADMIN field the value must be ‘User’ and not 1.
syncSchema

If set to true, IdentityIQ / IdentityNow application schema will be synchronized with the Mainframe Connector. Default value is true.

For example, <entry key="syncSchema" value="true"/>
smReadTimeout Timeout value in minutes for messages exchanged between IdentityIQ / IdentityNow and the Mainframe Connector for a transaction. Default value is 10 minutes. For example, <entry key="smReadTimeout" value="10"/>
failWhenSkip
failWhenWarn

Pre and Post Scripts are written as per customer's requirements. The Mainframe Connector in default considers, SKIP return code as success and WARN return code as failure. In some scenarios it may be required to consider SKIP as failure and WARN as success or vice versa, this can be achieved by following entries with accepted value between true or false. To implement these changes, add the following entries in the application debug page:

<entry key="failWhenSkip" value="false"/>
<entry key="failWhenWarn" value="true "/>
CGCertSubject

Before establishing the TLS communication channel with Connector Gateway, Provisioning Engine would validate the authenticity of the Connector Gateway. To implement this, add the CGCertSubject entry key in the application debug page as follows:

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

Provisioning Engine would check CN of the subject of certificate with the value provided in application configuration as mentioned in the above entry key. The CGCertSubject parameter is configurable only through the application configuration.

If CGCertSubject is not provided, then Provisioning Engine would validate the CN of the subject against the FQDN of the machine hosting Connector Gateway. This functionality is configurable in application configuration using the disableHostnameVerification parameter. If the value of disableHostnameVerification parameter is set to true, then Provisioning Engine would not validate CN of the subject name.

For example, <entry key="disableHostnameVerification" value="true"/>

Default value is false.
setDefaultGroupAndAccountOwner

(Only for RACF) Setting the value of setDefaultGroupAndAccountOwner to true sets the following respective values for Create and Update Account operations in RACF:

Create Account Operation

  1. If default group value is not provided, and if no entitlement or more than one entitlements are requested, then Mainframe Connector fails for that operation.
  2. If default group value is not provided, and if only one entitlement is requested then Mainframe Connector would set same entitlement value as default group.
  3. If account owner value is not provided, then Mainframe Connector would set account owner same as the default group.
    Set the value of setDefaultGroupAndAccountOwner to true as follows in the application debug page:
    <entry key="setDefaultGroupAndAccountOwner" value="true"/>

Update Account Operation

  1. If operation is to change default group value and if account owner value is not provided, then Mainframe Connector would update account owner same as of default group.
removeDefaultGroupConnection

(Only for RACF) If removeDefaultGroupConnection is set to true and during update default group operation, Connector Gateway would send flag to Mainframe Connector to drop the existing default group connection. Set the value of removeDefaultGroupConnection to true as follows in the application debug page/API page:

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

 

Enabling TLS Communication

The Transport Layer Security (TLS) protocol provides encryption, authentication and integrity to all applications. For using TLS secured communication for Mainframe Connector, TLS communication must be defined and configured in the following relevant components:

  • TCP/IP in the system where Mainframe Connector will be active
  • Connector Gateway
  • IdentityIQ / IdentityNow

For more information on enabling TLS communication on the above components, see Security Configurations for Mainframe Integration Components.

Enabling Traces

  1. (For IdentityIQ) Enable log4j tracing on sm package within the Application Server by adding the following line in the log4j.properties file:
    log4j.logger.sailpoint.connector.sm=debug

    (For IdentityNow) Enabling logs for Cluster in turn enables debug level logs for all Sources which uses that cluster.

  2. (For IdentityIQ) Save and reload the log4j.properties file.

On Connector Gateway:

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

    logger.file.level = debug
  2. Restart Connector Gateway.

 

Support for Account Aggregation Filter

IdentityIQ/IdentityNow now supports setting scope for account aggregation for Mainframe applications/sources. A list of strings can be configured in Start Filter Condition for Accounts field. Connector aggregates all the accounts from Mainframe applications/sources which starts with any of the configured character sets.

NOTE:

  • The filter strings do not support wild card characters like (*) or spaces( ).
  • Each filter string value must be a prefix of any account and must not be longer than 7 characters.

Perform the following steps to configure filters for Mainframe application in IdentityIQ/IdentityNow:

  1. Apply the FSD0135 PTF on Mainframe Connector.

    NOTE: For more information on the Mainframe E-Fixes and PTF's, see Mainframe E-Fixes.

  2. (For IdentityIQ) Navigate to Application Configuration Settings page on IdentityIQ ==> Aggregation Scope Settings ==> Start Filter Condition for Accounts field.
    (For IdentityNow) Navigate to Mainframe Source on IdentityNow ==> Advanced Options ==> Aggregation Scope Settings ==> Start Filter Condition for Accounts field.
  3. Set the values for the filter as separate strings in the list. For example, if one wants to aggregate the accounts starting with Emp_ or E24 then the filter list must have the following entries:
    Emp_
    E24
  4. Once the filters are configured, perform the Test Connection and save the application.
  5. Perform account aggregation so that only the accounts starting with configured filter strings to be aggregated.

 

Managing of X-ROL and X-SGP Entities for ACF2

This section describes the feature of managing X-ROL and X-SGP entities for ACF2 with the following prerequisites:

  • Mainframe Connector E-Fixes:
    • FSD0136, FSD0137, FSD0138
    • For provisioning of X-ROL and X-SGP as an Entitlement: FSD0153
      (For more information on the Mainframe Fixes and PTF's, see Mainframe Connectors Downloads)
  • ACF2 Version: CA-ACF2 R16
  • Latest IdentityIQ versions

 

Supported Features

Following features are supported:

  • Account aggregation aggregates the following entities:
    • Roles (X-ROL) and Sources (X-SGP) connections
    • Role direct and indirect permissions
    • RoleGroups and SourceGroups
  • (Only for IdentityIQ) Create, Update, Delete role and source
  • Requesting new role and source for an account
  • Remove existing role and source from an account
  • (Only for IdentityIQ) Aggregation of role and source as Entitlement
  • (Only for IdentityNow) Support to XROL and XSGP as additional entitlement attributes

 

Managing X-SGP

NOTE: X-SGP support is intended for supporting its implementation with the ACF2 for DB2 Option where names in the include/exclude lists at the bottom level non-group SOURCE entity are treated as LIDs (accounts).

  1. Add source schema in the application through application debug page as follows:
    <Schema aggregationType="group" descriptionAttribute="" displayAttribute="SourceName" featuresString="PROVISIONING" identityAttribute="SourceName" instanceAttribute="" nativeObjectType="source" objectType="source">
 <AttributeDefinition name="SourceName" required="true" type="string">
   <Description>The name of Source</Description>
 </AttributeDefinition>
 <AttributeDefinition name="isIncomplete" required="true" type="string">
   <Description>Obtained object data is incomplete</Description>
 </AttributeDefinition>
 <AttributeDefinition name="IncludeList" multi="true" required="true" type="string">
   <Description>List of users included in the Source</Description>
 </AttributeDefinition>
 <AttributeDefinition name="ExcludeList" multi="true" required="true" type="string">
   <Description>List of users excluded from the Source. This is subset of values from IncludeList</Description>
 </AttributeDefinition>
</Schema>
  2. Add the following attributes in account schema:

    Attributes Description Type/Value
    Sources List of sources to which this user belongs.

    Type: source
    Entitlement: true
    Multi-Valued: true
    Managed: true
    SourceGroups List of source groups to which this user belongs. Type: string
    Entitlement: false
    Multi-Valued: true
  3. Add create and update provisioning policies for source:
    • Create Source

      Attributes Type Value
      SourceName String Required: true
      IncludeList String

      Multi-Valued: true
      Required: true
      ExcludeList String

      Multi-Valued: true
    • Update Source

      Attributes Type Value
      IncludeList String

      Multi-Valued: true
      Required: true
      ExcludeList String Multi-Valued: true

(Only for IdentityIQ) Upgrading Existing ACF2 Application

To leverage this functionality with application already created prior to this release, ensure that your application has changes as described below:

  1. Add splConnectionAttributes attribute in application debug page as follows:
    <entry key="splConnectionAttributes">
    <value>
    <Map>
    <entry key="REFRESH" value="false"/>
    <entry key="TYPE" value="false"/>
    </Map>
    </value>
    </entry>
  2. Perform the following schema changes:
    1. Navigate to Application configuration settings page on IdentityIQ and click on Add Object Type button.
    2. In drop down box select role and click Ok.

      NOTE      : If your application already has Role schema, ensure that IncludeList and ExcludeList attributes are set as multivalued and featuresString="PROVISIONING" is also added in the schema.

    3. Add the new schema for source through application debug page as follows:
      <Schema aggregationType="group" descriptionAttribute="" displayAttribute="SourceName" featuresString="PROVISIONING" identityAttribute="SourceName" instanceAttribute="" nativeObjectType="source" objectType="source">
 <AttributeDefinition name="SourceName" required="true" type="string">
   <Description>The name of Source</Description>
 </AttributeDefinition>
 <AttributeDefinition name="isIncomplete" required="true" type="string">
   <Description>Obtained object data is incomplete</Description>
 </AttributeDefinition>
 <AttributeDefinition name="IncludeList" multi="true" required="true" type="string">
   <Description>List of users included in the Source</Description>
 </AttributeDefinition>
 <AttributeDefinition name="ExcludeList" multi="true" required="true" type="string">
   <Description>List of users excluded from the Source. This is subset of values from IncludeList</Description>
 </AttributeDefinition>
</Schema>

      NOTE: If your application already has Source schema, ensure that IncludeList and ExcludeList attributes are set as multivalued and featuresString="PROVISIONING" is also added in the schema.

    4. Navigate to Schema and add the following attributes in account schema:

      Attributes Description Type/Value
      Roles

      List of Roles to which this user belongs.

      		 Type: role
      Entitlement: true
      Multi-Valued: true
      Managed: true
      Sources List of sources to which this user belongs. Type: source
      Entitlement: true
      Multi-Valued: true
      Managed: true
      RoleGroups List of Role groups to which this user belongs.

      Type: string
      Entitlement: false
      Multi-Valued: true
      SourceGroups List of source groups to which this user belongs. Type: string
      Entitlement: false
      Multi-Valued: true
      AccountRoleDirectPermissions The direct permissions for account obtained from ROLESET rules. Type: string
      Entitlement: false
      Multi-Valued: true
      AccountRoleIndirectPermissions The indirect permissions for account obtained through role membership. Type: string
      Entitlement: false
      Multi-Valued: true
      isIncomplete Obtained object data is incomplete. Type: string
      Entitlement: false
      Multi-Valued: false
  3. Add the following provisioning policy for create, update Roles and Sources:
    • Create and Update Role

      Attributes Type Value

      Create Role
      RoleName String

      Required: true
      Description String

       
      IncludeList String

      Multi-Valued: true
      Required: true
      ExcludeList String Multi-Valued: true

      Update Role
      Description String

       
      IncludeList String

      Multi-Valued: true
      Required: true
      ExcludeList String Multi-Valued: true
      RoleDirectPermissions String Multi-Valued: true
      ReadOnly: true


    • Create and Update Source

      Attributes Type Value

      Create Source
      SourceName String

      Required: true
      IncludeList String

      Multi-Valued: true
      Required: true
      ExcludeList String Multi-Valued: true

      Update Source
      IncludeList String

      Multi-Valued: true
      Required: true
      ExcludeList String Multi-Valued: true

      NOTE: When XREF_SYSID_SCOPE is set to ALL_SYSTEMS in RSSPARM of mainframe connector PARM library, the active attribute must be added to the Role and Source entity in IdentityIQ/IdentityNow. The active attribute indicates the value as Y for Role/Source aggregated from current system/SYSID in which the Mainframe Connector for ACF2 is active. Only active roles would have Role direct permissions populated. Add and delete connection can be performed from/to active roles and sources only.

  4. Perform the following to edit and update PlanInitializerScript:
    1. Add the following code snippet after the import sailpoint.tools.*; statement:

              /**
        * Method to modify the attribute request to set IncludeList and ExcludeList for role and source.
        * This method converts Set operation into Add and Remove operation. This would avoid overwriting
        * any data present on the end system but not yet synced to IdentityIQ when this request was triggered.
        * For example :
        * Consider that IdentityIQ has "A,B,C" as IncludeList for role R, User triggers a request from
        * IdentityIQ to remove A and add D. In this case, IdentityIQ sends a plan to connector to SET B,C,D
        * as the values for IncludeList for role R. If ACF2 system has A,B,C,E as IncludeList for role R, this
        * request is going to overwrite it to set B,C,D, hence effectively unintentionally removing E from the
        * list. This method changes SET "B,C,D" to ADD "D" and REMOVE "A", hence avoiding any overwrite.
        * If this is not desired change in behaviour, remove this method and all its references from this
        * Plan Initializer rule.                        
        */
        private void modifyIncludeExcludeRequest (Application app, AttributeRequest listAttr, ObjectRequest req) {
          String groupType = req.getType();
          String groupId = req.getNativeIdentity();

          if (listAttr != null) {
            String attrName = listAttr.getName();
            String op = listAttr.getOperation().toString();

            if(op != null &amp;&amp; op.equalsIgnoreCase("Set")) {

              listAttr.setOperation(ProvisioningPlan.Operation.Add);

              ManagedAttribute ma = ManagedAttributer.getEntitlementOrObject(context, app, null, groupId, groupType);
              Object objDBValues = ma.getAttribute(attrName);

              if(objDBValues != null) {
                List dbList = new ArrayList();
                if(objDBValues instanceof List) {
                  dbList.addAll(objDBValues);
                } else if(objDBValues instanceof String) {
                  dbList.add(new String (objDBValues));
                }

                if((dbList != null) &amp;&amp; !(dbList.isEmpty())) {

                  Object objReqValues =  listAttr.getValue();
                  List reqList = new ArrayList();

                  if(objReqValues instanceof String) {
                    reqList.add(new String (objReqValues));
                  } else if(objReqValues instanceof List) {
                    reqList.addAll(objReqValues);
                  }

                  if(!reqList.isEmpty()) {
                    List tempListDB = new ArrayList();
                    tempListDB.addAll(dbList);
                    dbList.removeAll(reqList);
                    reqList.removeAll(tempListDB);

                    if(!reqList.isEmpty()) {
                      // list values to be added to the role or source includeList or excludeList
                      listAttr.setValue(reqList);
                    } else {
                      req.remove(listAttr);
                    }
                  } else {
                      req.remove(listAttr);
                  }

                  if(!dbList.isEmpty()) {
                    // list values to be removed from the role or source includeList or excludeList
                    // add new attribute request to remove the values
                    AttributeRequest att = new AttributeRequest(attrName, dbList);
                    att.setOperation(ProvisioningPlan.Operation.Remove);
                    req.add(att);
                  }
                }
              }
            }
          }
        }


    2. Search for ObjectOperation op = req.getOp(); and add the following code snippet below this line:
      if((op == ObjectOperation.Modify) &amp;&amp; (req.getType().equalsIgnoreCase("role") || req.getType().equalsIgnoreCase("source"))) {

    Application app = context.getObject(Application.class,req.getApplication());

    AttributeRequest incListAttr = req.getAttributeRequest("IncludeList");
    modifyIncludeExcludeRequest(app, incListAttr, req);

    AttributeRequest excListAttr = req.getAttributeRequest("ExcludeList");
    modifyIncludeExcludeRequest(app, excListAttr, req);
}

Enabling FIPS for Connector Gateway

  1. In the deployment directory i.e. the folder from where ConnectorGateway.jar is executed, add the bouncy castle jars.
    Download and add the following latest jar files from bouncycastle.org:

    • bc-fips-*.jar

    • bctls-fips-*.jar

    • bcpkix-fips-*.jar

  2. In the init.xml file,

    • set the value of enableFIPS to true

    • provide the encrypted value of trustStorePassword

    • provide the path of keystore and truststore and also configure the rest of parameters as usual.

  3. The keystore and truststore must be in BCFKS format. Following is the sample/reference command to create new BCFKS keystore from 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

    Sample/reference command to create 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

  4. Modify the java security file to add the bouncy castle provider in the beginning as follows and change the priority of rest of the providers:
    security.provider.1=org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider C:HYBRID;ENABLE{ALL}
    security.provider.2=org.bouncycastle.jsse.provider.BouncyCastleJsseProvider

  5. Once done, override the classpath to set to the deployment folder and run the connector gateway jar as follows from the deployment folder:
    java -cp ./* sailpoint.router.common.Main

  6. In order to view the debug SSL logs, run Connector Gateway using the following command :
    java -Djava.security.debug=all -Djavax.net.debug=SSL -cp ./* sailpoint.router.common.Main

Connector Gateway takes some time to initialize and synchronize with the Mainframe. Hence if you click on Test Connection soon, you may get some errors from the Mainframe. Hence, wait for Connector Gateway to initialize and connect to Agent.

RACF Only Features

This section describes the following features only supported for RACF:

Account / Group Connection

To set the group as the connection owner for that group, add the following attribute manually to the RACF-Full.xml file when upgrading IdentityIQ / IdentityNow from any previous version to the latest version of IdentityIQ / IdentityNow:

<entry key="splConnectionAttributes">
<value>
 <Map>
 <entry key="CONNECTION_OWNER" value="true"/>
</Map>
 </value>
</entry>

One connection/group is mandatory to create a RACF account. One of the requested groups would be marked as the Default Group for that account.

Support for Connection Attributes

With this feature, IdentityIQ / IdentityNow has the ability to manage:

  • System Privileges (SPECIAL, OPERATIONS, AUDITOR and ROAUDIT)
  • Connection Privileges (SPECIAL, OPERATIONS and AUDITOR)

System Privileges

The SYSTEM_ACCESS attribute on Account schema manages system privileges.

  • The Account aggregation fetches the SYSTEM_ACCESS properties along with other properties of the account. SYSTEM_ACCESS manages the following attributes:
    • SPECIAL
    • OPERATIONS
    • AUDITOR
    • ROAUDIT
  • The SYSTEM_ACCESS is Multi-valued Entitlement attribute hence, the values SPECIAL, OPERATIONS, AUDITOR and ROAUDIT are added as an Entitlement in Entitlement Catalog.
  • SYSTEM_ACCESS supports provisioning operations and certification like any other entitlement attribute.

NOTE:

  • If SYSTEM_ACCESS attribute is sent through provisioning plan along with USER_ADMIN and OPERATIONS attributes then, USER_ADMIN and OPERATIONS are ignored.
  • SYSTEM_ACCESS attribute creation is not supported in IdentityIQ / IdentityNow. At present only 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 Account schema by selecting the following in Advanced properties:
    • Entitlement
    • Multi-Value
    • Managed
  2. Select Manage Privileged Access checkbox on RACF - Full application configuration to enable the feature to manage Connection privileges.
  3. Apply the FSD0134 PTF on SailPoint Connector for RACF version 4.0.01.

NOTE: For more information on the Mainframe Fixes and PTF's, see Mainframe Connectors Downloads.

Connection Privileges

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

During group aggregation, IdentityIQ / IdentityNow creates three additional groups for each group that it receives from RACF system. The three additional groups are named in <Connection Privileges>.<Group Name> format where <Connecton Privileges> are SPECIAL, OPERATIONS and AUDITOR while <Group Name> is the name of the group that IdentityIQ / IdentityNow receives from RACF system.

If IdentityIQ / IdentityNow receives a Group named ENGG from RACF during group aggregation, this adds four groups in IdentityIQ / IdentityNow that is., ENGG, SPECIAL.ENGG, OPERATIONS.ENGG, AUDITOR.ENGG. These four entities can be requested and certified like any other entitlements.

The connection privileges can be managed with add/remove entitlement operation. If add access request is sent for Account John to connect to SPECIAL.ENGG then, after successful operation the connection of Account John with group ENGG would have SPECIAL privilege on RACF.

IdentityIQ / IdentityNow would display the following connections on Account John:

  • ENGG
  • SPECIAL.ENGG

Configurations for Connection Privileges

  • (For IdentityIQ) The support for connection parameters can be enabled by performing the following:
    1. Add the following attributes in the splConnectionAttributes section (if it does not exists) of the application debug page: <entry key="CONNECTION_ATTRIBUTES" value="true"/>

    2. Apply the FSD0134 PTF on SailPoint Connector for RACF version 4.0.01.

NOTE: For more information on the Mainframe Fixes and PTF's, see Mainframe Connectors Downloads.

  • (For IdentityNow) The connection privileges can be enabled by adding the following attribute using the IdentityNow REST API:

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

where,

    • <url> is the URL for the customer's IdentityNow 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: Remove the OWNER attribute, if it exists in the splConnectionAttributes section.

 

(Only for IdentityIQ) DELETE_DELAY Operation

When a user or group is deleted from IdentityIQ, RACF Connector can ensure that the user’s or group’s UIDs or GIDs are deleted from other profiles in the RACF database that refer to the user or group. This cleanup is accomplished through parameters in IdentityIQ and CTSC100 utility in RACF Connector.

Deleting RACF users and groups is not as easy as deleting a profile because other profiles in the RACF database may be referred to the user/group.

Delete user operation in IdentityIQ is controlled by the MODE parameter and Delayed Delete is decided by the MODE operand.

if (op == AccountRequest.Operation.Delete)
 {
 req.add(new AttributeRequest("MODE", "DELETE"));
 req.add(new AttributeRequest("DELAY", "N"));
 }

The following operation modes are available:

  • DELETE: Deletes the user without performing any cleanup operations.
  • SCAN: Scans the database and creates RACF commands for cleaning up the user from the database (the user is not deleted).
  • FULL: Identical to SCAN, but the cleanup commands are executed in order to clear the user occurrences from the database.
  • FORCE: Identical to FULL, but the user dataset profiles do not prevent a cleanup and they are deleted as part of the cleanup.
  • DELAY: Allows delayed execution of the RACF database scanning and delete operations.

To enable the DELETE_DELAY operation in IdentityIQ for account configuration, select the the mode of operation as either SCAN, FULL, or FORCE and set the value of DELAY operation as Y.

 

Support for Multi-Factor Authentication Attribute Management

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

NOTE: SailPoint recommends that you do not update MFA attributes with non-MFA attributes in a single request.

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/ Remove factors assigned to user
  • Add/ Remove policies assigned to user

Account Attributes

To support managing MFA attributes, add the following account schema attributes:

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 the 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 the factor 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 such attribute that must be included in the aggregation, must be individually added to the account schema.

Value: the value of the tag

Single-value

Provisioning Policy Attributes

The ability to manage MFA attributes provides support for assigning factors and policies as entitlements. To manage provisioning of MFA attributes for user, add the above account attributes (as applicable) to the provisioning request.

Additional Configuration Attributes

To enable the MFA attribute management feature for RACF, add the following additional configuration attributes to the application xml through debug pages:

  • MFA.OOBPOLICY: A multi-value attribute which includes the list of policies that must be added to the user when the corresponding factor associated with user is added.

    RACF connector needs to send the OOBPOLICY with the policies in it as a regular multi-value attribute.

    MFA.OOBPOLICY will be configured in application xml as follows :

    <entry key="MFA.OOBPOLICY">
    <value>
    <Map>
    <entry key="PassTicket">
    <value>
    <List>
    <String>PolicyA</String>
    <String>PolicyB</String>
    </List>
    </value>
    </entry>
    <entry key="RSA_SecureID">
    <value>
    <List>
    <String>PolicyP</String>
    <String>PolicyQ</String>
    </List>
    </value>
    </entry>
    </Map>
    </value>
    </entry>

  • MFA.MAP.<factor-name>.<IBM-factor-name>: Enables an easy conversion between the original IBM’s factor names in the AZFxxxxx format to a readable free text names describing the factor, such as RSA_SecureID. The corresponding values for these attributes should be set to false always.

    The MAP attributes will be defined as special account attributes in the application xml as follows:
    <entry key="splAccountAttributes">
    <value>
    <Map>
    <entry key="MFA.MAP.PassTicket.AZFPTKT1" value="false"/>
    <entry key="MFA.MAP.RSA_SecureID.AZFSIDP1" value="false"/>
    </Map>
    </value>
    </entry>

Managing Resources and Permissions

This section describes the resource and permission management features available in the IdentityIQ connector for RACF, and how to configure and manage them.

NOTE: You need to be on one of the following IdentityIQ releases, or a later release within the major version, to use these features:

  • 8.2p4
  • 8.3p2
  • 8.4

Resources and permissions are managed independently, with no links within IdentityIQ to the resource permissions or to the users and groups which have permissions to access them.

NOTE: The values presented in the following topics are examples. Where applicable, substitute values relevant to your requirements.

For information on configuring the ability to manage resources and permissions, see Managing Resources and Permissions in the Integrating SailPoint with RACF guide.

IdentityIQ Specific Configurations

This section describes the following configurations which are applicable only for IdentityIQ:

 

Target Aggregation Implementation in Mainframe Connectors

Users can use Target aggregation feature to aggregate User, Group permissions of each mainframe based application users and group which has permissions on Mainframe resources (such as datasets , CICS...). In addition, it is also possible to revoke these permissions from IdentityIQ so the relevant Mainframe Connectors will drop the relevant permission. The Target Aggregation functionality is supported only for the following Mainframe Connectors:

  • CA-Top Secret
  • CA-ACF2
  • RACF
Implementing Target Aggregation

For implementing the target aggregation, the following configuration parameters must be updated:

Parameters Description
splAceAttributes The list that contains keywords to synchronize ACE entity.
splResourceAttributes

The list that contains keywords to synchronize resource entity.

If the POS attribute not found error is displayed on Mainframe Connector for deleting the permissions, perform the procedure specified in Adding POS keyword for ACF2 application.
splTargetPermissionsInterestingKwds The keywords mentioned in splTargetPermissionsInterestingKwds key are subset of keywords defined in splAceAttributes key that is used to form the permissions string. These keywords are not sent to Mainframe Connector while keyword synchronization.
fieldDelimiter and listDelimiter

The delimiters for field separator and list separator can be modified in the respective application registry file. The default values for field and list delimiter are # and ; respectively.

The resources and permissions will be updated in the respective account as a string in delimited format. Customer can define the delimiters for field separator and list separator by modifying the following keys in respective application registry file in IdentityIQ for Mainframe Connector:

<entry key="fieldDelimiter" value="#"/>
<entry key="listDelimiter" value=";"/>

The default values for field and list delimiter are # and ; respectively.

NOTE: Ensure that the delimiter character does not appear as part of USERID, GROUPID or permission strings that would be aggregated.

 

To implement Target Aggregation Users must perform the following steps:

1 - Synchronize keywords

To aggregate the permissions, keywords for resource and ACE must be synchronized. Users must perform Test Connection for Mainframe application. Following are the three set of keywords maintained for Target Aggregation:

  • splAceAttributes
  • splResourceAttributes
  • splTargetPermissionsInterestingKwds

Users can add/remove these keywords from the list by modifying and importing the following respective application registry file in IdentityIQ for Mainframe Connector:

  • RACF-Full.xml
  • ACF2-Full.xml
  • TopSecret-Full.xml

If any keyword must be added/deleted in the permissions list then adding/deleting the keyword in splTargetPermissionsInterestingKwds tag and running the target aggregation will populate the value of the keyword on record.

For example, if the splTargetPermissionsInterestingKwds contains the following list of keywords as in the application debug page:

<entry key="splTargetPermissionsInterestingKwds">
 <value>
 <Map>
 <entry key="ACCESS" value="false"/>
 <entry key="INFO.ACC_COUNT" value="false"/>
 <entry key="WHEN.APPCPORT" value="false"/>
 <entry key="WHEN.CONSOLE" value="false"/>
 <entry key="WHEN.JESINPUT" value="false"/>
 <entry key="WHEN.PROGRAM" value="false"/>
 <entry key="WHEN.SYSID" value="false"/>
 <entry key="WHEN.TERMINAL" value="false"/>
 </Map>
 </value>
</entry>

And if the user does not want IdentityIQ to display the fields starting with WHEN, then user must modify the list to the following in the application debug page:

<entry key="splTargetPermissionsInterestingKwds">
 <value>
 <Map>
 <entry key="ACCESS" value="false"/>
 <entry key="INFO.ACC_COUNT" value="false"/>
 </Map>
 </value>
</entry>

2 - Unstructured Target Configuration on Mainframe application

  1. Configure unstructured targets for the application you want to execute target aggregation. Provide the following details on Unstructured Target Configuration:
    • Name: Provide name to the created unstructured configuration. For example, RACFUnstructuredTargetConfig.
    • Correlation Rule: Create a correlation rule to correlate the permissions and entities in IdentityIQ.
  2. The following sample code can be used for correlation:

    import sailpoint.api.Correlator;
    import sailpoint.tools.xml.XMLObjectFactory;
    private String ATTR_USER_OBJECT= "USER_ID";
    private String ATTR_GROUP_OBJECT= "GROUP_ID";
    Map returnMap = new HashMap();
    if ( isGroup ) { returnMap.put(Correlator.RULE_RETURN_GROUP_ATTRIBUTE,"nativeIdentity");
     returnMap.put(Correlator.RULE_RETURN_GROUP_ATTRIBUTE_VALUE, nativeId);
    } else {
    returnMap.put(Correlator.RULE_RETURN_LINK_IDENTITY, nativeId);
    }
    System.out.println("Incomming ["+nativeId+"] correlated
    ["+XMLObjectFactory.getInstance().toXml(returnMap)+"]");
    return returnMap;
  3. Depending on the type of the Mainframe Connector, select Target Source type and other attributes:
    • Application Type: RACF - Full
      Target Source Type: PE2 RACFCollector

      Attributes Description
      RACF Target Resource Name Provide RACF Target Resource name.
      Target Resource Type Provide RACF Target Resource Type.
      Volume Provide RACF Target Resource volume.
      Resource Get Type Specify ID or PREFIX.
      Generic Type Specify Yes (Generic) or No (non-Generic).

 

    • Application Type: TopSecret - Full
      Target Source Type: PE2 TSSCollector

      Attributes Description
      TSS Target Resource Name Provide Top Secret Target Resource name.
      Target Resource Type Provide Top Secret Target Resource Type.
      Resource Get Type Specify ID or PREFIX.

 

    • Application Type: ACF2 - Full
      Target Source Type: PE2 ACF2Collector

      Attributes Description
      ACF2 Target Resource Name Provide ACF2 Target Resource name.
      Target Resource Type Provide ACF2 Target Resource Type.
      ACF2 ruleset Type None (specific) or PREFIX or NEXTKEYS.
      NOTE: ACF2 now supports Account Direct, Account Indirect permission aggregation and Group direct aggregation. Details can be found at the Manage Direct and Indirect Permissions with Mainframe Connector for CA-ACF2 page.

3 - Execute a task to aggregate resources

To aggregate permissions create New Target Aggregation task. Enter the name for the task and select appropriate Target Source to scan targets from the list and the Unstructured Target configured for the application. When the task gets completed successfully you can view the permissions in the Identity’s Entitlement tab.

4 - Run certification process to revoke permission

To revoke permission through certification run Refresh Identity Cube before running certification and follow the certification process.

 

Settings for Configuring Password Interceptor and Online Interceptor

Password Interception: SailPoint IdentityIQ provides the capability of Password Interception, by which password of an account changed on managed system is intercepted to IdentityIQ. New password is intercepted and sent to IdentityIQ to propagate to other managed systems on which the account is defined.

Online Interception: SailPoint IdentityIQ provides the capability of Online Interception, by which any account or group or account-group connection changed on managed system is intercepted to IdentityIQ.

For proper functioning of the Password Interception or Online Interception, the Password Interception or Online Interception settings are mandatory. Settings for Password Interception/Online Interception are same, so this must be defined only once in IdentityIQ

Password Interception or Online Interceptor is not enabled by default. There are few steps that need to be performed in order to enable it on Mainframe Connector and IdentityIQ. The value of hostName in ServiceDefinitions of SMListener and ResourceEvent are case sensitive.

NOTE: In IdentityIQ, Online Interceptor updates may cause loss of information related to association of X-ROL and X-SGP with the accounts. It is recommended not to use this feature in combination with Online Interceptor. Though the Password Interceptor functionality of the Mainframe Connector can continue to be used without any adverse effect.

To enable Password Interception or Online Interceptor on IdentityIQ, add the following attributes in Service definition:

  1. To open the ServiceDefinitions navigate to IdentityIQ debug page => ServiceDefinition => SMListener and add the attribute and hostname as follows:
    • Add the following attribute in SMListener:
      <Attributes>
      <Map>
      <entry key="applications" value="Application name"/>
      <entry key="retryInterval" value="5" />
      </Map>
      </Attributes>

      NOTE: To configure multiple applications for password interceptor, add multiple names in application value as follows:
      <entry key="applications" value="App1,App2"/>

    • Add the hostname as follows:
      <ServiceDefinition created="1347280738108" hosts="hostName" id="2c9095d439b02f0b0139b030973c00e9" modified="1347285339111" name="SMListener">
  2. To open the ServiceDefinitions navigate to IdentityIQ debug page => ServiceDefinition => ResourceEvent and add the hostname as follows:
    <ServiceDefinition created="1347280738124" hosts="hostName" id="2c9095d439b02f0b0139b030974c00ea" modified="1347285354945" name="ResourceEvent">

In the preceding command lines, the value of hostName in ServiceDefinitions of SMListener and ResourceEvent must be the name/IP of host where IdentityIQ Server is running. User must define only one IdentityIQ host if there are multiple instances of IdentityIQ Servers running. This will start SMListener Service on one server where the interceptors sent from Mainframe Connector would be processed.

When IdentityIQ starts it will start a thread per application for which password interception is enabled. This thread is responsible for receiving the delta changes from that application. If any change is made to the above attributes or if you enable or disable encryption for the application that is configured to receive password changes, the IdentityIQ server must be restarted for the changes to take effect.

Password Interceptor and Online Interception are supported for the following Mainframe Connectors:

  • CA-ACF2: To enable Password Interceptor or Online Interceptor on CA-ACF2, refer to the SailPoint IdentityIQ Connector for CA-ACF2 Administration Guide.
  • CA-Top Secret (TSS): To enable Password Interceptor or Online Interceptor on Top Secret, refer to the SailPoint IdentityIQ Connector for CA-Top Secret Administration Guide.
  • RACF: To enable Password Interceptor or Online Interceptor on RACF, refer to the SailPoint IdentityIQ Connector for RACF Administration Guide.

 

Configuring Aggregation Rules for Online Interceptor

Following are the different types of Aggregation Rules to be used:

  • Correlation Rule
  • Creation Rule
  • Manager Correlation Rule
  • Customization Rule
  • Managed Entitlement Customization Rule

Perform the following procedure:

  1. Navigate to IdentityIQ debug page and select ServiceDefinition in Object Browser.
  2. Open the ResourceEvent and add the following entry key:

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

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

  3. Save the object and restart IdentityIQ Server to restart the services.

 

Adding POS Keyword for ACF2 Application

  1. Navigate to application debug page and open ACF2 application for which the error is observed.
  2. Add the POS keyword in splAceAttributes and splTargetPermissionsInterestingKwds as follows and save the page:
    <entry key="POS" value="false"/>
  3. Perform the following change in IdentityIQ Application Schema to update IdentityIQ that the POS keyword is added:
    • Navigate to Application ==> ACF2 application and modify any property (for example, description of any keyword).
    • Save the application.
  4. Perform Test Connection to update the keyword list on Mainframe Connector.
  5. Run Target Aggregation and Certification. Now try deleting a permission.

 

Revision History for LDAP Mainframe Connectors

The LDAP Mainframe Connectors include the following connectors:

LDAP Mainframe Connectors Application Type
IdentityIQ for RACF LDAP Mainframe RACF LDAP
IdentityIQ for TopSecret LDAP Mainframe Top Secret LDAP

 

The following tables list the revision history for the IdentityIQ version specific LDAP Mainframe Connectors documents:

  • 8.2 Documents
IdentityIQ Version Description/Revision History Document Title/Date Of Release
8.2

The following Integration Modules now support IBM Tivoli Directory Server for z/OS 2.4 with SDBM LDAP back end:

  • RACF LDAP
  • Top Secret LDAP

8.2 SailPoint Mainframe Integration Modules Guide
  • 8.1 Documents
IdentityIQ Version Description/Revision History Document Title/Date Of Release
8.1

Endpoint identification algorithms have been enabled by default in JAVA from version 8u181. Endpoint identification algorithms can be disabled by enabling disableLDAPHostnameVerification parameter in the following applications:

  • RACF LDAP
  • Top Secret LDAP
8.1 SailPoint Mainframe Integration Modules Guide
8.1 Patch 1
  • RACF Connector: Supports z/OS 2.4
  • ACF2 Connector:
    • Supports managing of X-ROL and X-SGP Entities for ACF2
    • Supports setting scope filter for account aggregation
  • RACF and Top Secret Connector: Supports setting scope filter for account aggregation
 8.1.1 SailPoint Mainframe Integration Modules Guide
8.1 Patch 3
  • RACF LDAP and Top Secret LDAP: Supports IBM z/OS v2.4
  • ACF2 Connector: Supports managing of X-ROL and X-SGP as additional group entities
 8.1.3 SailPoint Mainframe Integration Modules Guide
8.1 Patch 4
  • RACF Connector: Supports managing MFA related attributes for RACF systems configured for MFA. Upgrade RACF connector installed on the RACF system to leverage this feature.
 8.1.4 SailPoint Mainframe Integration Modules Guide

 

  • 8.0 Documents
IdentityIQ Version Description/Revision History Document Title/Date Of Release
8.0 RACF LDAP Integration Module now supports IBM Tivoli Directory Server for z/OS 2.3 with SDBM LDAP backend IdentityIQ 8.0 Product Documentation
8.0 Patch 1 No changes SailPoint Integration Guide version 8.0.1
8.0 Patch 2

Endpoint identification algorithms have been enabled by default in JAVA from version 8u181. Endpoint identification algorithms can be disabled by enabling disableLDAPHostnameVerification parameter in the following applications:

  • RACF LDAP
  • Top Secret LDAP
SailPoint Integration Guide version 8.0.2
8.0 Patch 3 No changes SailPoint Integration Guide version 8.0.3
8.0 Patch 5
  • ACF2 connector supports managing X-ROL and X-SGP as additional group entities.
  • Top Secret LDAP and RACF LDAP connectors support IBM Tivoli Directory Server for z/OS 2.4 with SDBM as a back end.
 8.0.5 SailPoint Mainframe Integration Guide

 

Reference Documents

 

Recent Update

The ConnectorGateway-Feb-2022 version now supports Java Development Kit 1.11 and 1.17 on all supported platforms for all features. This version also upgrades log4j libraries used in the product to log4j 2.17.1. In addition, this release also addresses few known issues reported for earlier releases of Connector Gateway.

Labels (1)
Labels:
Attachments
SailPoint Mainframe Integration Modules 8.1 Patches.zip
Comments
anand_joshi_capgemini
‎Feb 16, 2022 06:51 AM
‎Feb 16, 2022 06:51 AM

@Ganesh_Kulkarni :Can you please  add more  detail  for the "Support for Account Aggregation Filter" for example does it support all the logical operator Like "And" , " OR" " Not" , does it work for all the attribute  present in schema , if possible please add more examples for the filter 

Version history
Revision #:
91 of 91
Last update:
‎Dec 12, 2023 03:02 PM
Updated by:
SailPoint Employee
 
View Article History