Integration between IBM Security Identity Manager and IBM Security Identity Governance

Content

Abbreviations

The following abbreviations are sometimes used in this document.

• ISIGADI: IBM Security Identity Governance and Administration Data Integrator, also referred to as Data Integrator. Data Integrator synchronizes data between IBM Security Identity Manager and IBM Security Identity Governance.
• ISIM: IBM Security Identity Manager
• ISIG: IBM Security Identity Governance
• ITDI or TDI: IBM Tivoli Directory Integrator. After version 7.2 the name is IBM Security Data Integrator. IBM Tivoli Directory Integrator version 7.1.1 is used with Data Integrator version 7.0.1.
• ISIGADI_SOL_DIR: The solution directory in IBM Tivoli Directory Integrator where the Data Integrator solution is installed.

Intended audience

This document is intended for security deployment specialists who need to integrate IBM Security Identity Management with IBM Security Identity Governance.

Overview and features of the IBM Security Identity Governance and Administration Data Integrator

The IBM Security Identity Governance Administration Data Integrator solution (hereafter Data Integrator) is designed to transfer information about people, roles, services, groups and their organization from IBM Security Identity Manager to IBM Security Identity Governance. The solution is built using IBM Tivoli Directory Integrator and operated by running one or more IBM Tivoli Directory Integrator AssemblyLines (hereafter AssemblyLine or assembly line). An AssemblyLine is an IBM Tivoli Directory Integrator application.

Table 1 shows how IBM Security Identity Manager entities are mapped into IBM Security Identity Governance entities.

Table 1: Default Mapping of IBM Security Identity Manager Entries to IBM Security Identity Governance Entities

IBM Security Identity Manager entry type	IBM Security Identity Governance entity
Organization	Org Unit
Organizational Unit	Org Unit
Location	Org Unit
Admin Domain	Org Unit
Business Partner Organization Unit	Org Unit
Organization Role	Business Role
Service	Account Configuration(1) + Application(1)
Group	Permission
ISIM System Role	Permission
Person	ISIG User
Account	Account

In the version 7.0.1 release, the new assembly line ISIGtoISIM is provided to fulfill the entitlement changes from IBM Security Identity Governance to IBM Security Identity Manager. In IBM Security Identity Governance, when there is entitlement (authorization) changes for a user, IBM Security Identity Governance stores these events to the data store so that these events can be shared with external applications. The ISIGtoISIM assembly line periodically processes these events from the IBM Security Identity Governance data store and synchronizes them to IBM Security Identity Manager. The following list shows the types of entitlement change events that are processed by ISIGtoISIM AssemblyLine.

• Add permission to a user
• Remove permission from a user
• Lock (suspend) an account
• Unlock (restore) an account
• Create an account
• Remove an account
• Add a role to a user
• Remove a role from a user

Script files are also provided in version 7.0.1 to start and stop the IBM Tivoli Directory Integrator server and assembly lines and to check the status of assembly lines. The following scripts are provided.

• startSrv: Starts the ISIGADI ITDI server (idmdisrv) as a daemon process
• stopSrv: Stops the ISIGADI ITDI server
• startAL: Starts the specified assembly line on the running ISIGADI ITDI server
• stopAL: Stops the specified assembly line on the running ISIGADI ITDI server
• showStat: Shows the status of all assembly lines running on ISIGADI ITDI server

For more details on how to run these commands, see the following file on the installed system:

ISIGADI_SOL_DIR/isigadi_bin/README.txt

Deployment topologies

Deployment topology is slightly different depending on whether you are running IBM Security Identity Manager version 6 on physical machines or IBM Security Identity Manager VA version 7.0, as shown in Figure 1.

Note the following abbreviations in Figure 1:

• ISIM: IBM Security Identity Manager
• ISIG: IBM Security Identity Governance
• ISIGADI: IBM Security Identity Governance Administration Data Integrator, also Data Integrator in this document

Figure 1: Deployment topologies

Full load and incremental load operations

The Data Integrator has two modes:

• Full load: Full load is typically executed only once. It migrates all entity data. The AssemblyLine named Load reads content from the IBM Security Identity Manager LDAP server and loads the data as entities in IBM Security Identity Governance.
• Incremental load (delta): The AssemblyLine named Delta listens for changes in the LDAP server. It then migrates the detected changes to the corresponding entities in IBM Security Identity Governance.

The Data Integrator uses the IBM Security Identity Governance Java API for adding, modifying and deleting IBM Security Identity Governance entities, requiring that the API jar files be made available to IBM Tivoli Directory Integrator, as described in the "Installation" section.

Entitlement fulfillment operations

In version 7.0.1, the entitlement change is fulfilled from IBM Security Identity Governance to IBM Security Identity Manager.

The AssemblyLine named ISIGtoISIM periodically processes entitlement changes in IBM Security Identity Governance and fulfills these changes to IBM Security Identity Manager.

The Data Integrator uses the IBM Security Identity Manager Web Services API to fulfill the entitlement changes from IBM Security Identity Governance to IBM Security Identity Manager.

Installation prerequisites

Check your systems to be sure the prerequisites are satisfied. The following operating systems are supported:

• Red Hat Enterprise Linux 6.5
• Windows 7

The following software must be installed:

• IBM Security Identity Manager version 6.0.0.4 or IBM Security Identity Manager version 7.0 VA
• IBM Security Identity Governance version 5.1
• IBM Tivoli Directory Integrator version 7.1.1 with fix pack 4 or newer. Later versions are named IBM Security Directory Integrator.
• IBM Security Directory Server version 6.3.

  Use the same IBM Security Directory Server instance that IBM Security Identity Manager is using.

  The changelog feature must be enabled in order for incremental loads to be run. See the documentation for IBM Directory Server. The simplest way to do it is to use the IDS Configuration Tool, as described in the "Installation procedure" section, step 1.

• IBM DB2 Universal Database™ Enterprise Server Version 10.1

  Data Integrator uses a DB2 database to store entity mapping information. The database for Data Integrator can be created either on the same DB2 instance that IBM Security Identity Manager uses or on a separate DB2 instance.

Installation procedure

Use the following procedure to install the Data Integrator solution.

1. Enable the changelog for IBM Security Identity Server

To use the Configuration Tool to enable the changelog, follow these steps:

1. Stop the IBM Security Identity Manager server
2. Stop the IBM Security Directory Server.
3. In the Configuration Tool, click Manage changelog in the task list on the left.
4. In the Configure/unconfigure changelog window, select the Enable change log database check box.
5. In the Maximum number of log entries box, click Unlimited if you want an unlimited number of entries in the change log. If you want to limit the number of entries, click Entries and type the maximum number of entries you want recorded. The default is 1,000,000 entries.
6. In the Maximum age box, accept the default of Unlimited if you want entries to remain in the change log indefinitely. You can also click Age and type the number of days and hours for which you want each entry to be kept.
7. Click Update.

Messages are displayed while the change log is being enabled. Click Close when the task is complete.

See more information on changelog in the IBM Security Directory Server Knowledge Center.

http://www.ibm.com/support/knowledgecenter/SSVJJU_6.3.0/com.ibm.IBMDS.doc/install157.htm

2. Prepare the database used for Data Integrator

Data Integrator requires a database in which to store referential links between IBM Security Identity Manager and IBM Security Identity Governance, as well as keeping track of the current change state in IBM Security Identity Manager. It is recommended that you use the DB2 instance that is part of the IBM Security Identity Manager installation. However, you may also use a separate instance.

In order to use the DB2 instance provided with IBM Security Identity Manager, create a database with 16k pagesize and create a database user (see IBM Knowledge Center for documentation specific to your version of DB2 and operating system).

To create a database on DB2, perform the following steps:

1. Create a user with administrator privileges
2. Using the administrator credentials, create the database and give the user the DBADM privilege:

        db2 CREATE DB ididb AUTOMATIC STORAGE YES PAGESIZE 16 K     db2 CONNECT TO ididb     db2 GRANT DBADM ON DATABASE TO USER idiuser  

Replace ididb with the name of the database. Replace idiuser with the user name of the administrative user you created. Make a note of database name, user id, and password for this database. These information is needed for updating DBMAP.properties file later.

Note: Data Integrator uses the IBM Security Directory Integrator System Store within the database you created. Consult the IBM Security Directory Integrator documentation on using database management systems other than DB2 for the IBM Tivoli Directory Integrator System Store.

3. Enable SSL Connections (if used)

If there will be SSL connections to the IBM Security Identity Manager LDAP directory or the Database server, then client certificates must be imported into the IBM Tivoli Directory Integrator keystore. This procedure is described in the IBM Tivoli Directory Integrator documentation.

4. Install the Data Integrator solution

You need the following information to configure the ISIGADI.

• Host name and port for the IBM Security Identity Manager Directory Server
• Credentials for IBM Security Identity Manager Directory Server
• URLs for the IBM Security Identity Manager Web Services API (new for version 7.0.1)
• Oracle database host name, port, and SID for the ISIG database
• Credentials for ISIG database
• DB2 database information for the database you created in 2. Prepare the database used for Data Integrator.
• Both the Installation Directory and the Solution Directory for IBM Tivoli Directory Integrator that will be used for ISIGADI

Important notes about IBM Tivoli Directory Integrator

During the installation of IBM Tivoli Directory Integrator, you are prompted to select the Solution Directory to be used for the installed ITDI Server. The solution directory is the working directory for the ITDI server instance and it contains a server-specific properties file, solution.properties. That file controls the configuration and behavior of the server.

The ISIGADI solution itself consists of group of AssemblyLines that are specified in a single XML solution configuration file, ISIGADI.xml. You can have one ITDI server instance running multiple solutions or you can have multiple server instances running different solutions. Each ITDI server instance must have its own Solution Directory and corresponding configuration.

An ITDI server needs to bind to a port. The ports must be available or the server will not start. The following settings in the solution.properties file control the ports to use.

• api.remote.naming.port=1099: The Java API port of the server
• web.server.port=1098: Provides web service features, like the IBM Tivoli Directory Integrator browser dashboard.

Whenever multiple ITDI servers need to be run on the same machine, each must be given its own Solution Directory and each solution.properties file must define unique ports for the two port settings.

The ITDI server running on the default solution directory is often called as default ITDI server. If you are not using this default ITDI server for another solution, then you can use this solution directory for ISIGADI ITDI server.

If you are already using this solution directory for another solution, then create a new solution directory for ISIGADI and use a separate ITDI server instance. The Delta and ISIGtoISIM assembly lines are supposed to run all the time in order to synchronize the data continuously between IBM Security Identity Manager and IBM Security Identity Governance.

This technote assumes that you are using the default solution directory for ISIGADI.

Do not use the ISIGADI directory integrator server instance to run other solutions. How to create a new solution directory is out of the scope of this document. See IBM Knowledge Center documentation for IBM Tivoli Directory Integrator and the following resources.

• Getting Started guide in the Knowledge Center for ITDI version 7.1.1
• IBM Tivoli Directory Integrator blog articles:
  • What is the Solution Directory?
  • Changing the Solution Directory?
  • Portable Solutions

All relative paths used in the solution are resolved from the Solution Directory. For example, the IBM Tivoli Directory Integrator solution configuration file ISIGADI.xml must be located in a Solution Directory sub-folder named ISIGADI.

Finding the default ITDI solution directory

Follow these steps to find the default Solution Directory of an IBM Tivoli Directory Integrator application that is specified during the installation.

1. Go to the IBM Tivoli Directory Integrator installation folder (for example V7.1.1). On Linux the folder is /opt/IBTM/TDI/V7.1.1 by default, but depends on how you installed IBM Tivoli Directory Integrator.
2. Go to the bin sub-folder.
3. Open the defaultSolDir script file. For Windows, the file name is defaultSolDir.bat and for Linux, the file name is defaultSolDir.sh.

   The script file contains a single line that sets the Solution Directory location.

Get Oracle JDBC driver and copy it to TDI_HOME/jar directory

From the Oracle website, download the Oracle JDBC driver ojdbc6.jar file for ISIG Oracle database version. You can download it from: http://www.oracle.com/technetwork/database/features/jdbc/index-091264.html

Copy ojdbc6.jar file to the jars/3rdparty/others directory under the TDI installation directory. You need this driver so that ISIGtoISIM assembly line can read the ISIG entitlement change events from the ISIG Oracle database.

Installing the Data Integrator

1. Copy the ISIGADI-7.0.1.zip file to a temporary directory on the host where IBM Tivoli Directory Integrator is installed.

   Note: Make sure you have the right zip file for the version of IBM Security Identity Governance that you are running.

2. Extract the files in the temporary folder, which will create three sub-directories: jars, license, and soldir.
3. Copy the TEMP/jars folder to the IBM Tivoli Directory Integrator Installation Directory.
   • Example on Windows systems:

     c:\Program Files\IBM\TDI\V7.1.1\

   • Example on Linux systems:

     /opt/IBM/TDI/V7.1.1/

   The copy operation merges the files from TEMP/jars into the jars sub-directory in the IBM Tivoli Directory Integrator installation directory. Make sure you have write permissions on the directories.

4. Copy the ISIGADI and isigadi_bin directories from TEMP/soldir to your Solution Directory of your IBM Tivoli Directory Integrator. The abbreviation for the solution directory is ISIGADI_SOL_DIR.

   For an upgrade, rename the ISIGADI directory to ISIGADIv7.0 and copy over the directories so that you can use the existing properties from version 7.0 as a reference. Once you have copied the directories, you should have ISIGADI and isigadi_bin directories in your solution directory (ISIGADI_SOL_DIR).

5. Update the properties files in the ISIGADI_SOL_DIR/ISIGADI directory

Table 2 lists the files that are copied.

Table 2: JAR files Copied to Tivoli Directory Integrator

Destination folder	File name
TDI-InstallDir/jars/3rdparty/IBM/ISIG	AgCoreClientV1.0.000.jar CommonbackendV3.1.000.jar DataAccessToolV2.1.000.jar jbossall-client-fixed.jar ProfileManagerV7.1.000.jar SecurityApiV7.1.000.jar
TDI-InstallDir/jars/connectors	isigadi-connectors.jar
TDI-InstallDir/jars/functions	isigadi-dn-child-of-fc.jar isigadi-dn-part-fc.jar isigadi-normalize-dn-fc.jar isigadi-prop-value-oc-fc.jar

Table 3 lists the files that must be copied to the Tivoli Directory Integrator Solution Directory. Although the table includes some information on the various properties files, see Table 4, Table 5, and Table6 for more details.

Table 3: Data Integrator Files in the Solution Directory

Parameter name	Description
ATTRIBUTES.properties	Properties file that describes permissions (ISIM group) attributes in IBM Security Identity Manager LDAP.
DBMAP.properties	Properties file with configure access to the database system that will be used by the Data Integrator to store relationships between IBM Security Identity Manager entries and IBM Security Identity Governance entities. The following properties are used by the data integrator. Do not modify them. sql.com.ibm.db2.jcc.DB2Driver.check: SQL statement used to check the existence of the relationship map table named ISIG_MAP. sql.com.ibm.db2.jcc.DB2Driver.create: DDL statement used to create the relationship map table named ISIG_MAP. sql.com.ibm.db2.jcc.DB2Driver.truncate: DDL statement used to remove all records from the relationship map table named ISIG_MAP. See Table 5 for more details.
ISIG.properties	Configuration parameters for connections to both IBM Security Identity Governance and to the IBM Security Identity Manager LDAP server. In addition, there are also properties that define the LDAP search base and search filters used to retrieve various types of entries to be transferred to IBM Security Identity Governance entities. The filters used to read group and services are specified by the following properties: isim.ldap.itim.service.filter: Filter for services isim.ldap.group.filter: Filter for groups The search base used to read most types of entries is defined by the following property: isim.ldap.search.base The exception is for reading User entries, where the following property defines the search base from which user entries will be read: isim.ldap.sys.user.search.base You can also specify a semi-colon-separated list of object classes to skip during a Delta operation in the following file. isim.ldap.delta.skip.objectClasses Example contents of the file: erDSMLInfoService; eradjndifeed; ercsvfeed; erPIMService; erDSML2Service; erjndifeed See Table 4 for more details.
ISIM.properties	New for version 7.0.1 Contains ISIM properties used by the ISIGtoISIM assembly line to access the ISIM Web Services API. The API is used to fulfill entitlement changes from ISIG to ISIM. See Table 6 for more details.
ISIGADI.xml	The Tivoli Directory Integrator solution file that provides the Data Integrator functionality.

Use a text editor to modify properties files. Further instructions are provided in the next section.

5. Define hostname for IBM Security Identity Governance server

To access the IBM Security Identity Governance API, the system where IBM Tivoli Directory Integrator is running must be able to resolve the host name of the IBM Security Identity Governance server. Usually this done by configuring DNS services for the network where these systems are running.

If the systems cannot find each other through DNS, there may be an issue with host name mapping. To resolve the issue, you can modify the hosts file on the server where IBM Tivoli Directory Integrator is running.

Look in the following locations for the hosts file.

• Windows systems:

  /windows/system32/drivers/etc

• Linux systems:

  /etc

Add the following line to define the hostname of the IBM Security Identity Governance server:

ip_address host_name ideas

• ip_address: IP4 address of the IBM Security Identity Governance server. You can get it from IBM Security Identity Governance VA Web Admin console by accessing the following tab:

  Manage System Settings > Management Interface > Interface M.1

• host_name: Host name of IBM Security Identity Governance server. You can get it from IBM Security Identity Governance VA Web Admin Console by access the following tab:

  Manage System Settings > Management Interface > General

Example:

192.168.159.128 ideas.crossideas.com ideas

Note: The server does not need to be restarted when the hosts file is changed.

Configuring the Data Integrator

1. Set and encrypt properties

You should add encryption for properties by adding the {protect}- prefix and a password to property names.

Example: The ideas.password {protect}-ideas.password=Passw0rd

Enter the password value in clear text. It is encrypted the next time the solution is run.

The properties that need to be configured are listed in the following tables. Table 4 shows the set of properties that control access to both IBM Security Identity Governance and the IBM Security Identity Manager LDAP directory.

Table 4: Properties in ISIG.properties

Property name	Description	Example
isig.url	URL to IBM Security Identity Governance server, in the following format: jnp://ISIG_HOST_NAME:1099 ISIG_HOST_NAME is the host name of the IBM Security Identity Governance server.	jnp://ideas.crossideas.com:1099
isig.user	IBM Security Identity Governance administrator user name	admin
isig.password	IBM Security Identity Governance administrator password	admin
isig.realm	IBM Security Identity Governance realm for this Data Integrator instance	ideas
isig.rootorg.id	ID for the root organization in IBM Security Identity Governance that IBM Security Identity Manager organization structure will be added to. Default is root.	root
isig.rootorg.name	Name for the root organization in IBM Security Identity Governance to which the IBM Security Identity Manager organization structure is added. Default is "ACME Corp."	ACME Corp.
isig.db.user	Database user for ISIG database (new in v7.0.1)	IGA_CORE
isig.db.password	Password for the ISIG database user (new in v7.0.1)	isig
isig.db.schema	Database schema for ISIG database (new in v7.0.1)	IGA_CORE
isig.db.url	Database URL for ISIG database (new in v7.0.1) In the example, the following values are used. isig.myco.com: Oracle database host 1521: Oracle database port xe: Oracle database SID	jdbc:oracle:thin:@isig.myco.com:1521:xe
isig.db.driver	JDBC driver for ISIG database. (new in v7.0.1)	oracle.jdbc.OracleDriver
isim.ldap.url	LDAP URL for IBM Security Identity Manager internal LDAP	ldap://localhost:389 ldaps://192.168.15.15:636
isim.ldap.bind.dn	Distinguished name for IBM Security Identity Manager internal LDAP user	cn=root
isim.ldap.bind.password	Password for IBM Security Identity Manager internal LDAP user
isim.ldap.search.base	LDAP search base for Data Integrator queries	ou=org, dc=com
log.load.debug	If set to true, enables debug logging for Load operations, Default is false.	false
log.load.info	If set to false, disables info logging for Load operations. Default is true.	true
log.delta.debug	If set to true, enables debug logging for Delta operations, Default is false.	false
log.delta.info	If set to false, disables info logging for Delta operations. Default is true.	true
log.isig.debug	If set to true, enables debug logging for ISIGtoISIM operations, Default is false.	false
log.isig.info	If set to false, disables info logging for ISIGtoISIM operations. Default is true.	true

Table 5 lists properties that define connection settings to the database used by the Data Integrator to maintain its relationship information. It also lists property values used to set up the relationship table.

Table 5: Properties in DBMAP.properties

Property name	Description	Example
db.driver	JDBC driver class to use (DB2 only)	com.ibm.db2.jcc.DB2Driver
db.url	JDBC URL for Data Integrator system database, in the form jdbc:db2://host:port/db_name	jdbc:db2://myDB2host:50000/ididb
db.user	User name for the data integrator to use to access this database.	idiuser
db.password	Password for db2.user
db.password	Database schema name that you specified for the database.	idiuser

Table 6 lists the properties in ISIM.properties file. The ISIM.properties file has the properties that are needed for data integrator to access ISIM Web Services APIs to fulfill the entitlement changes from ISIG to ISIM.

Table 6: Properties in ISIM.properties

Property name	Description	Example
isim.username	ISIM system user who has the authorizations necessary to update users and accounts	ITIM_Manager
isim.password	Password for isim.username	secret
certificate.baseurl	Base URL of the ISIM HTTPS URL. If you can access the ISIM Console UI though the URL https://hostip:9443/itim/console, then it should be set to https://hostip:9443/. This property is used by the ImportCertificate assembly line to import the ISIM server certificate to ITDI’s truststore so that the ISIGtoISIM assembly line can access the ISIM Web Services APIs to fulfill the entitlement changes from ISIG to ISIM.	https://hostip:9443/
isim.wsdl.url.session	URL for ISIM Web Service API. It is set with the default value. Update the http://hostIP:port section with the information for your site.	https://hostip:9443/
isim.wsdl.url.request	URL for ISIM Web Service API. It is set with the default value. Update the http://hostIP:port section with the information for your site.	https://hostip:9443/
isim.wsdl.url.account	URL for ISIM Web Service API. It is set with the default value. Update the http://hostIP:port section with the information for your site.	https://hostip:9443/
isim.wsdl.url.person	URL for ISIM Web Service API. It is set with the default value. Update the http://hostIP:port section with the information for your site.	https://hostip:9443/
isim.wsdl.url.account	URL for ISIM Web Service API. It is set with the default value. Update the http://hostIP:port section with the information for your site.	https://hostip:9443/
db.password	URL for ISIM Web Service API. It is set with the default value. Update the http://hostIP:port section with the information for your site.	https://hostip:9443/

2. Configure the SSL certificate for the ISIM 7.0 VA system

Check to see if your ISIM VA system has a self-signed certificate with the subject set to localhost. If it does, then you need to use the following procedure to generate and install a new self-signed certificate that uses an explicit host name. Each step in the procedure is documented in detail later in this section.

1. Create a self-signed certificate and keystore file using keytool
2. Update the ISIM VA server certificate

If you do not have a correct certificate, ISIGADI cannot access IBM Security Identity Manager Web Services APIs on ISIM VA system even if the server certificate is imported to the truststore file.

Checking the ISIM VA self-signed certificate

1. In the ISIM VA appliance dashboard, go to Configure Identity Manager > Application Server Certificate Management.


Figure 2: Checking the self-signed certificate in the ISIM VA appliance dashboard

2. In the certificate properties, check the Subject.
   • If it is set to the explicit host name, skip the rest of this section and go to 3. Configure the setEnvfile.
   • If it is set to CN=localhost, then you need to generate and install a new self-signed certificate. Follow the rest of the steps in this section, steps 2.1 to 2.5.
   

   Figure 3: SSL Certificate properties

2.1 Create a self-signed certificate and keystore file using keytool

The keytool comes with the Java JDK and is used for managing the key and certificate. If you do not have the JDK installed, use the JDK provided with TDI 7.1.1. It is in TDI_INSTALL_DIR/jvm/jre/bin.

Example: On Windows, if the TDI is installed in C:\Program Files\IBM\TDI\V7.1.1, then keytool.exe is in C:\Program Files\IBM\TDI\V7.1.1\jvm\jre\bin.

The following example shows how to create a self-signed certificate and a keystore file named keystore.jks on Windows. The procedure is similar on Linux systems.

Notes on the example

• The –storetype parameter is not specified. The default keystore type JKS is used.
• To answer the prompt What is your first and last name, enter the host name for the ISIM VA system.
• Write down the password you enter for –storepass. You will need it later.
• For more information, see the keytool documentation.

To start the process, enter the following commands. The example shows the directory of the JDK provided with TDI. The line break in the keytool command is for clarity. Do not use a line break when you enter the command.

cd "C:\Program Files\IBM\TDI\V7.1.1\jvm\jre\bin"
keytool” -genkey -keyalg RSA -alias isimva -keystore keystore.jks -storepass password
-validity 360 -keysize 2048

The keytool command prompts you for information for the certificate.

  What is your first and last name?    [Unknown]:  myisimserver.mydomain.com  What is the name of your organizational unit?    [Unknown]:  MyOrg  What is the name of your organization?    [Unknown]:  IBM  What is the name of your City or Locality?    [Unknown]:  CM  What is the name of your State or Province?    [Unknown]:  CA  What is the two-letter country code for this unit?    [Unknown]:  US  Is CN=myisimserver.mydomain.com, OU=Security, O=IBM, L=CM, ST=CA, C=US correct? (type "yes" or "no")    [no]:  yes  Enter key password for :          (RETURN if same as keystore password):  

2.2 Update the ISIM VA server certificate

1. In the ISIM VA appliance dashboard, go to Configure Identity Manager > Application Server Certificate Management.


Figure 4: Updating the ISIM VA server certificate

2. In the Application Server SSL Certificate page, click Update.
3. In the Upload Keystore dialog, select or enter the following information:
   • File: The keystore file you created
   • Keystore Password: Enter a password. Write it down for use later.
   • Keystore Type: The default of JKS is shown.
   

   Figure 5: Upload Keystore dialog

4. Verify the certificate information in the updated Application Server SSL Certificate page.

   Figure 6: Updated ISIM VA server certificate

3. Configure the setEnv file

Script files are provided to start and stop the server, start and stop assembly lines, and show the status of assembly lines.

Update the setEnv file. It is in the following location:

ISIGADI_SOL_DIR/isigadi_bin/systype/setEnv

Replace systype with your system type, either win or linux.

Note: on Linux systems, be sure the script files are executable.

chmod +x filename

The setEnv file has comments that explain how to use the scripts. You can also get more information from the README file in the following directory:

ISIGADI_SOL_DIR/isigadi_bin/

4. Import the ISIM server certificate to the ITDI server

If you access IBM Security Identity Manager through the HTTPS protocol, then you need to run the following assembly line to import the IBM Security Identity Manager server certificate to the TDI trust store. If you are using ISIM VA system, your need to do this step to import the ISIM Server certificate because you can only access IBM Security Identity Manager server through HTTPS. If you are using non VA version of ISIM and want to use HTTPS for Identity Manager, then you also need this step. If you are using non VA version of ISIM and you are using HTTP for Identity Manager, then you can skip this step. If you are using an ISIM VA system, before running this step, verify that you have checked the certificate on the ISIM VA system. Create a new certificate and update the ISIM Server certificate if needed (step 2).

1. Go to the script directory.

   ISIGADI_SOL_DIR/isigadi_bin/systype/ and replace systype with your system type, either win or linux.

2. Start the server if it is not running .

   For Windows systems:

   startSrv

   For Linux systems:

   ./startSrv

3. Open a separate command window. Run the ImportCertificate assemblyline, using the syntax for Windows systems or Linux systems as appropriate.

   startAL ImportCertificate

5. Move IsimDeltaChangeKey from the server store into DB2

If you are installing ISIGADI for the first time, you can skip this step. If you are upgrading from the previous version, you need to move the existing IsimDeltaChangeKey to the IBM DB2 database used by ISIGADI. The procedure only needs to be performed once.

The key IsimDeltaChangeKey is used to store the last index number of the change log for IBM Security Identity Manager Directory Server.

• When a full load starts (Load assembly line), this index number is stored in the IBM Tivoli Directory Integrator system store. The system store is a Derby database by default.
• When an incremental load runs (Delta assembly line) after the full load, it starts to process the change log at the index to make sure to process all the changes in IBM Security Identity Manager after the full load is started.

To move IsimDeltaChangeKey to the IBM DB2 database used by ISIGADI, perform the following steps.

1. Go to the script directory.

   ISIGADI_SOL_DIR/isigadi_bin/systype/

   Replace systype with your system type, either win or linux.

2. Start the server if it is not running.

   For Windows systems:

   startSrv

   For Linux systems:

   ./startSrv

3. Open a separate command window. Run the MoveSystemStoreToDB2 AssemblyLine.
   • Windows systems

     startAL MoveSystemStoreToDB2

   • Linux systems

     ./startAL MoveSystemStoreToDB2

   In the command window where you started the server you see a value that represents the move. It is in the following form:

   datestamp IsimDeltaChangeKey:number

4. Verify the move. Run startAL ShowIsimDeltaChangeKey

   In the command window where you started the server you see a value in the DB2 database. It is in the following form:

   INFO: [ShowIsimDeltaChangeKey/WriteIteratorStateKey] IsimDeltaChangeKey:number

The number shown by MoveSystemStoreToDB2 should match the number shown by ShowIsimDeltaChangeKey. If they match, the commands are synchronized correctly.

6. Verify the configuration

The Verify AssemblyLine verifies that configuration parameters have been set correctly. It tests the availability of property files and connection settings to IBM Security Identity Governance and IBM Security Identity Manager. To verify the configuration, perform the following steps:

1. Change directory to the IBM Tivoli Directory Integrator solutions directory.

   ISIGADI_SOL_DIR/isigadi_bin/systype

   Replace systype with your system type, either win or linux.

2. Start the server if it is not running.

   For Windows systems:

   startSrv

   For Linux systems:

   ./startSrv

3. Open a separate command window. Run the Verify AssemblyLine.
• Windows systems

  startAL Verify

• Linux systems

  ./startAL Verify

The output from this operation is both displayed to the commandline and captured in the Verify.log file in the ISIGADI/logs sub-folder of the IBM Tivoli Directory Integrator Solution Directory. If all tests run successfully then this AssemblyLine will display the following message:

Configuration successfully verified!

Otherwise error messages are displayed that indicate problems in the configuration.

Operating Data Integrator

When you start using ISIGADI for the first time, you need to perform the following operations in order.

1. Perform an initial load from IBM Security Identity Manager to IBM Security Identity Governance using the Load AssemblyLine.
2. Start continuous incremental synchronization from IBM Security Identity Manager to IBM Security Identity Governance using the Delta AssemblyLine.
3. Start continuous entitlement fulfllment synchronization from IBM Security Identity Governance to IBM Security Identity Manager using the ISIGtoISIM AssemblyLine.

This section provides details on each of the operations.

Prerequisite: Start the TDI Server

The TDI server must be running before you run any AssemblyLines. To start the TDI server, perform the following steps.

• Change directory to the IBM Tivoli Directory Integrator solutions directory.

  ISIGADI_SOL_DIR/isigadi_bin/systype

  Replace systype with your system type, either win or linux.

• Start the server using the startSrv command.

  startSrv for Windows systems
./startSrv for Linux systems

Initial Full Load from ISIM to ISIG using the Load assembly line

If you are upgrading from ISIGADI version 7.0 to version 7.0.1 and you already ran a full load using version 7.0, you do not need to perform the full load again.

To perform the initial full load operation, perform the following steps:

1. Change directory to the IBM Tivoli Directory Integrator solutions directory.

   ISIGADI_SOL_DIR/isigadi_bin/systype

   Replace systype with your system type, either win or linux.

2. Run the Load AssemblyLine using the command line for your operating system.
   • Windows systems

     startAL Load

   • Linux systems

     ./startAL Load

The time that the Load operation requires depends on the amount of information in IBM Security Identity Manager that needs to be converted and migrated to IBM Security Identity Governance entities. The AssemblyLine captures and writes log output to log files in the ISIGADI_SOL_DIR/ISIGADI/logs directory.

Let the Load operation complete before starting incremental operations. Use the showStat command to check if Load is finished and stopped.

Incremental Synchronization from ISIM to ISIG using the Delta assembly line.

After the initial full load is completed, you may run the incremental synchronization process as needed. Do this by performing the following steps:

1. Change directory to the IBM Tivoli Directory Integrator solutions directory.

   ISIGADI_SOL_DIR/isigadi_bin/systype

   Replace systype with your system type, either win or linux.

2. Run the Delta AssemblyLine using the command line for your operating system.
   • Windows systems

     startAL Delta

   • Linux systems

     ./startAL Delta

If any write operations to IBM Security Identity Governance fail during a Load or Delta operation, then a repair record is captured in the Repair-List. The Repair-List is described in the Troubleshooting section. The Delta operation periodically retries these failed items by performing a Repair operation.

Whenever the Repair operation successfully retries a failed item, it is removed from the Repair-List, allowing you to repeat this operation as needed as you work with issues that are blocking the writes.

Entitlement fulfillment synchronization from ISIG to ISIM using the ISIGtoISIM assembly line

After the initial full load is completed, you may run the entitlement fulfillment synchronization process as needed. Do this by performing the following steps:

1. Change directory to the IBM Tivoli Directory Integrator solutions directory.

   ISIGADI_SOL_DIR/isigadi_bin/systype

   Replace systype with your system type, either win or linux.

2. Run the ISIGtoISIM AssemblyLine using the command line for your operating system.
   • Windows systems

     startAL ISIGtoISIM

   • Linux systems

     ./startAL ISIGtoISIM

Stopping Incremental Synchronization Operations

In version 7.0.1 the Delta assembly line runs continuously once it is started.

The Delta assembly line is kept running without using the “KeepAlive” schedule. The “KeepAlive” schedule is an assembly line scheduling feature that keeps an assembly line running when the solution configuration file is loaded to the ITDI server. The "KeepAlive" schedule has been removed from the Delta assembly line.

The synchronization work is performed by the DeltaSynch assembly line. If the DeltaSynch assembly line stops, the Delta assembly line restarts it. To stop incremental synchronization, both Delta and DeltaSynch must be stopped at the same time.

To stop the Delta assembly line, you need to stop both Delta and DeltaSynch assembly lines. If you only stop the DeltaSynch, the Delta assembly line will restart the DeltaSynch automatically. If you only stop Delta, then the DeltaSynch will be still running.

To stop the incremental synchronization operation, perform one of the following operations:

If you need to stop the incremental synchronization operation, you can use one of the following methods:

• Run stopAL Delta,DeltaSynch on the command line.
• Use the browser-based Dashboard in IBM Tivoli Directory Integrator. Stop the Delta AssemblyLine, then stop the DeltaSynch AssemblyLine.

Stopping entitlement fulfillment synchronization operations

The ISIGtoISIM assembly line runs continuously once it is started. Stop the assembly line to stop entitlement fulfillment synchronization.

Run stopAL ISIGtoISIM.

Stopping all assembly lines

Run stopAL all.

Stopping the TDI server

Run stopSrv.

Checking the status of assembly lines

Run showStat.

Monitoring Data Integrator

The Load, Delta and ISIGtoISIM assembly lines display all error messages in the console and write them to the log files. The console lets you monitor the progress of operations.

You can use the IBM Tivoli Directory Integrator Dashboard to see that the desired AssemblyLine is running. You can also use it to start or stop assembly lines. The Dashboard is a web application that starts when the TDI server instance starts. For each server instance, the Dashboard runs on a port specified by the web.server.port property in your solution.properties file.

To access the Dashboard, enter the URL and port number of the ITDI server, followed by the path /dashboard.

The example shown in Figure 7 uses my_sdi.mydomain.com as the URL and 1098 as the port (the default):

http://my_sdi.mydomain.com:1098/dashboard

Note that Figure 7 shows a version of the product that is branded IBM Security Directory Integrator.

Figure 7: Using the Directory Integrator Dashboard to monitor Data Integrator

The Data Integrator instance is shown as ISIGADI in the Dashboard.

Select ISIGADI to see information about its AssemblyLines. Figure 3 shows a portion of the display.

Figure 8: Dashboard showing AssemblyLines for Data Integrator

• To start or stop an AssemblyLine: Select the AssemblyLine, then click the Start or Stop button displayed at the top of the window.
• To view the log output of an AssemblyLine: Select the AssemblyLine. See the Log tab at the bottom of the window.
• The highlighted text in Figure 8 shows the current version of IBM Tivoli Directory Integrator and also the maximum memory size that the server can use. You should have IBM Tivoli Directory Integrator 7.1.1 with fix pack 4 or the newer version. If you need to increase the maximum memory size for the ITDI server, you need to update tdi_install_dir/ibmdisrv script file to include the –Xmx flag. For example, if you want to increase the maximum memory size to 2G then you can add -Xmx2g as shown in the following example.

  "%TDI_JAVA_PROGRAM%" -Xmx2g -classpath "%TDI_HOME_DIR%\IDILoader.jar" %ENV_VARIABLES% com.ibm.di.loader.ServerLauncher %*

Updating the SDK Used By Data Integrator

Data Integrator has dependencies on libraries in IBM Security Identity Governance. They are a set of JAR files under TDI-InstallDir/jars/3rdparty/IBM/ISIG directory. When the IBM Security Identity Governance appliance is updated with fix packs, these JAR files may be updated as well. See Table 2 for the list of the JAR files.

Use the following procedure to download the JAR files update the Data Integrator installation.

1. Download SDK package from IBM Security Identity Governance appliance using the following URL.

   https://ISIG_HOST_NAME/SDK/sdk.zip

   Replace ISIG_HOST_NAME with the URL or IP address of the IBM Security Governance appliance.

2. Download the sdk.zip file and copy it to a temporary directory on the Data Integrator server.
3. Unzip the file. Copy all the JAR files in the SDK\lib directory to TDIInstallDir\jars\3rdparty\IBM\ISIG directory.

Customizing Data Integrator

You can customize Data Integrator to support additional IBM Security Identity Manager adapters. POSIX adapters and LDAP adapters are supported by default.

Support for additional IBM Security Identity Manager adapters

Data Integrator supports IBM Security Identity Manager adapters by specifying the mapping of the group metadata in the ATTRIBUTES.properties file. If additional IBM Security Identity Manager adapters are used, then additional mapping properties must be added to these properties.

For each adapter, the following properties must be added:

     class.$account_object_class$.group=$group_membership_attr$     class.$group_object_class$.description=$group_description_attr$     class.$group_object_class$.name=$group_name_attr$     class.$account_object_class$.groupitem.name=$group_id_attr_for_account$  

The parameters in the properties have the following definitions.

• $account_object_class$: Account object class for the adapter defined in the account profile
• $group_object_class$: Group object class for the adapter defined in the group profile
• $group_membership_attr$: Account attribute used for the group membership
• $group_name_attr$: Name attribute defined in group profile
• $group_description_attr$: Description attribute defined in group profile.

For example, here are the mapping properties required for the Posix Linux Adapter:

  class.erPosixLinuxAccount.group=erPosixSecondGroup  class.erPosixLinuxGroup.description=description  class.erPosixLinuxGroup.name=erPosixGroupName  class.erPosixLinuxAccount.groupitem.name=erPosixGroupName   class.erLDAPUserAccount.group=erldapgroupname  class.erLDAPGroupAccount.description=erLdapGroupDescription  class.erLdapGroupAccount.name=erldapgrouprdn  class.erLDAPUserAccount.groupitem.name=erldapgrouprdn  

Troubleshooting

Informational and error messages are displayed in the console where the Data Integrator operation is executed using the ibmdisrv command, as described in the "Operating Data Integrator" section. Log files are written to the ISIGADI_SOL_DIR/ISIGADI/logs folder where the current log output (with extension .log). The log folder contains log output and history from previous runs. The history files have extensions .1 through .10. Table 6 lists the log files.

Note: Be sure to include log files whenever reporting incidents to support.

The Load, Delta, and ISIGtoISIM operations produce a set of log files of three types when they run: Debug, Info, and Error. Table 7 shows a list of log files.

• Debug: Contains verbose log output with information used to troubleshoot issues. This log option is disabled by default, and can be enabled by setting the relevant log property to true. See Table 4 for a list of properties.
• Info: Contains status messages and the final report, as well as any error messages. This log option is enabled by default. It can be disabled by setting the relevant log property to false. See Table 4 for a list of properties.
• Error: Contains only errors and warning messages from the operation. It is useful for quickly locating problems with an operation. This log option is always enabled.

Table 7: Log files Found in ISIGADI/logs

Log file name	Description
load-debug.log	Debug log file for Load operations.
load-info.log	Info log file for Load operations.
load-error.log	Error log file for Load operations.
delta-debug.log	Debug log file for Delta operations.
delta-info.log	Info log file for Delta operations.
delta-error.log	Error log file for Delta operations.
verify.log	The log output for Verify operations.
isig-to-isim-debug.log	Debug log file for ISIGtoISIM operations.
isig-to-isim-info.log	Information log file for ISIGtoISIM operations.
isig-to-isim-error.log	Error log file for ISIGtoISIM operations.

When an error occurs, the following information is written to the log.

• Error message: Cause of the error.
• Error details: Additional information used for debugging.
• Current LDAP entry: LDAP entry from IBM Security Identity Manager being processed when the error occurred.
• Changelog entry: Delta operations only. Complete listing of theChangelog entry being processed when the error occurred.
• Stackdump: Technical listing of the call stack at the moment when the exception occurred. Be sure to save it and send it support to help them troubleshoot your problem.

The Repair-List

When a write operation to IBM Security Identity Governance fails, an entry is written to a Repair-List that is used by the Repair operation. The Repair retries the synchronization of failed entities. The Repair-List is a stored in file repair-list.json in the ISIGADI_SOL_DIR/ISIGADI/repair folder.

Entries in the Repair-List are removed when an item has been retried and successfully written to IBM Security Identity Governance. You can edit the repair-list file and remove any entries that Data Integrator is not able to handle.

This file contains a JSON object for each failed entity write operation:

{"timestamp":1415789401714,"action":"modify","error":" ROLE_ILLEGAL","dn":”erUid=…”}

The properties captured for each IBM Security Identity Governance write error are listed in Table 8.

Table 8: Properties Captured in Repair-List.json

Log file name	Description
timestamp	When the write failure occurred.
action	The write operation performed: add, modify or delete
error	The error that occurred.
dn	The DN of the IBM Security Identity Manager entry that was being synchronized when the error occurred.

Synchronizing ISIG Oracle database system time with ISIG system time

If the Oracle database used by IBM Security Identity Governance has a system time not in synch with the IBM Security Identity Governance system time, the entitlement change event gets processed at the wrong time. To check the Oracle database system time, you can run the following SQL statement on the Oracle database.

select sysdate from dual;

If the Oracle system time is different than the host operating system time, then you need to change the time of the host computer again.

To change the Oracle database system time, perform following steps.

1. Stop all the Oracle processes.
2. Change the OS system time.
3. Restart the Oracle database.

See Oracle documentation for information on how to stop and start Oracle processes and Oracle databases.

Weird status shown on ERC Status column of OUT Events table (!emanager.stato.3!)

When the entitlement is assigned to or removed from a user, this entitlement change event is shown on OUT Queue so that it can be shared with external application such as data integrator. After the data integrator processes the entitlement change event, it updates the ERC Status of this event. The ERC status can have three possible statuses in ISIG 5.1:

• Unprocessed: Not processed by external application.
• Success: Processed successfully by external application.
• Error: Processed by external application but error happened.

You might see an additional status !emanager.stato.3!: This status means that the event was processed by the external application but ignored. This status occurs whenever the event is processed and ignored by data integrator.

For example, this status occurs when a permission that only exists on the ISIG side is assigned to a user, who is ported over from ISIM.This !emanager.stato.3! status is shown after data integrator process this event. It means this event is processed by the data integrator but it is ignored because there is no matching service group for this permission on ISIM.