Contents: Introduction High-Level Overview Customer Scenarios Design considerations Customer environment settings Registry supported Performance Security Concerns Configuration File Examples Running the utility Where to install? What needs to be done before running the utility? How to execute the Directory Integrator utility? How to check the execution results? References About the authors Rate this article Subscriptions: dW newsletters dW Subscription (CDs and downloads)

Sam Yang (sayang@us.ibm.com), Advisory Software Engineer , IBM
Edward Whitehead (edward.whitehead@us.ibm.com), Advisory Software Engineer , IBM

5 March 2004

This article introduces the user data importing and synchronization utility for IBM / Tivoli security products developed using IBM Directory Integrator 5.1.2 as the application framework.

Introduction
Many companies today are interested in increasing the security of their IT infrastructure. One way companies can achieve this goal is by using tools to implement and enforce their IT security policies. IBM’s Tivoli division sells two products that can help with this goal - IBM Tivoli Identity Manager and IBM Tivoli Access Manager.

IBM Tivoli Identity Manager is a product for managing user and account definitions. By controlling account definitions on systems, it allows a company to control which systems a user can access.

IBM Tivoli Access Manager is an access control product. It enforces access control policy to prevent unauthorized access to protected resources. Access Manager can be used to protect access to many types of system resources - from individual files to Web sites.

The Identity Manager and Access Manager products complement each other. While Identity Manager controls which user accounts may exist on a system, Access Manager controls the operations that a user is authorized to undertake on the system. In order to do these tasks, both products maintain registries of users. The products enforce user access and authorization policy for the users defined in their registries.

After installing Identity Manager, its user registry must be populated so it can manage system access for those users. Because Identity Manager manages the user definitions in Access Manager, Identity Manager can populate the Access Manager user registry. A technique for the initial population of the Identity Manager user registry is one of the topics of this paper.

After Identity Manager and Access Manager are both deployed, and their respective user registries are both populated, there might be an ongoing need to update the values of the user attributes in Access Manager as they are modified in Identity Manager. This paper will describe a technique for management, or synchronization, of Access Manager user attributes from Identity Manager.

User Data Importing and Synchronization utility
This article introduces the User Data Importing and Synchronization Utility developed using IBM Directory Integrator 5.1.2 as the application framework.

Directory Integrator is a data migration and synchronization product with built-in support for many registries and data sources on many different platforms. It is an ideal tool for this type of integration solution.

The reader should be familiar with the high-level concepts in the Access Manager and Identity Manager products in order to understand the solutions described.

High-Level Overview
The initial population of the Identity Manger user registry may be done with user definitions from any source. This paper describes Directory Integrator based tools for populating Identity Manager user definitions from a corporate directory or an Access Manager user registry. If your user definitions are not in one of these locations, the implementation described in this paper can be modified to use other sources of user definitions.

After Access Manager and Identity Manager are installed, configured, and populated with user definitions, the value of some user attributes will inevitably change. Identity Manager provides a rich set of features for updating user attribute values. Since Access Manager can be configured to use the value of user attributes when making authorization decisions, the values changed in the Identity Manager user registry must be updated in the Access Manager user registry too. This update will ensure that Access Manager’s authorization decision is based on the correct values. The Access Manager user registry can be kept up to date by using a Directory Integrator-based synchronization tool that updates the Access Manager user registry with values from the Identity Manager user registry.

Customer Scenarios
Below are descriptions of three different deployment scenarios for a customer using both Identity Manager and Access Manager. Each scenario describes the tools that are available to assist with the deployment. The tools themselves are described in detail later in the paper.

Access Manager is deployed and all the customer’s user definitions have already been created in the Access Manager user registry. Now Identity Manager is installed. In this situation, the Identity Manager administrator would like to import the user data already defined in the Access Manager user registry to the Identity Manager user registry, so Identity Manager is the central location for user management.

To import the users in the Access Manager user registry to Identity Manager, the administrator can use either the TAMtoTIMImport or MDTAMtoTIMImport tasks. Use TAMtoTIMImport for an Access Manager deployment with a single domain or MDTAMtoTIMImport for an Access Manager deployment with multiple domains.

After the Identity Manager users are created, the Identity Manager administrator can do a reconciliation of the Access Manager service in Identity Manager to create the matched Access Manager accounts in Identity Manager. The Identity Manager reconciliation feature imports accounts from the agent to the server. The accounts are assigned to Identity Manager users based on the value of the alias user attribute. The value of alias must match the imported account name. Because the TAMtoTIMImport and MDTAMtoTIMImport tasks will set the Identity Manager user’s alias attribute, the ownership of the reconciled Access Manager accounts will be automatically determined

Neither Access Manager nor Identity Manger is installed. The company has all its user definitions in a corporate directory for use by other applications. Now they install both Identity Manager and Access Manager. In this situation, the Identity Manager administrator would like to import the user definitions from the corporate directory into Identity Manager.

The administrator can use the DirectorytoTIMImport task to import the existing user definitions from the directory to Identity Manager. Identity Manager can be configured so that the imported users are provisioned with an Access Manager account. After the provisioning occurs, both the Identity Manager and Access Manager user registries will be fully populated.

Both Access Manager and Identity Manager are deployed and being used. Some authorization policy, which uses the value of several Access Manager user attributes, has been defined in Access Manager. Identity Manager interfaces are being used to manage the attributes of Identity Manager users. Because user attributes are being updated in the Identity Manager user registry, but not in the Access Manager user registry, Access Manager does not have the correct value of user attributes when making authorization decisions.

The TIMtoTAMSync task can be used in this situation to update the Access Manager user registry with changes made in the Identity Manager user registry.

Design considerations

DSMLv2 enhancement in Identity Manager 4.5 and Directory Integrator 5.1.2
In Identity Manager Release 4.5, a provisioning service type called “IDI Data Feedâ€_ is supported for exchanging user data between Directory Integrator and the Identity Manager server. The “IDI Data Feedâ€_ service uses the Directory Services Markup Language version 2 (DSMLv2) format to communicate with the Directory Integrator. While in Directory Integrator version 5.1.2, the DSMLv2 EventHandler and the DSMLv2 support in the JNDI connector are added. This addition greatly enhances the integration capability between the Directory Integrator and Identity Manager. The solutions described in this article use a Directory Integrator JNDI connector with DSML2InitialContextFactory driver to import the user entries to Identity Manager.

Configuration files, AssemblyLines, Connectors and work mode
The development for this utility involves the design of Directory Integrator configuration files. A Directory Integrator configuration file contains one properties file for customer settings and several AssemblyLines (ALs). An AssemblyLine is for a specific processing task and consists of a number of connectors that operate in different modes on different data resources.

The connector types used in the utility include:

• LDAP connector
• Lotus Notes connector
• LDAP changelog connector
• JNDI connector
• File system connector

• Iterator: This connector processes all the data records under the defined directory (called search base), which passes the search filter in series.
• Lookup: This connector searches the data records and retrieves the attributes that meet the defined condition (called link criteria).
• AddOnly: In this mode, the connector creates data records in the data resource. The records are defined by mapping the working attributes passed from the previous connectors.
• Update: In this mode, the connector searches and updates the data record that meets the link criteria.

Customer environment settings
An administrator who runs these solutions should be able to provide authentication credentials for Identity Manager and Access Manager for use within the AssemblyLines. The environment parameters include host name, user ID, password, and so on. All the environment parameters are stored in the properties files. In this utility, the properties files use the same name as configuration files but with .properties as the suffixes. The properties file content is imported into the configuration file when it is loaded. After first time use, the properties file can be encrypted if encryption is requested by an administrator.

Registry supported
For importing user definitions from Access Manager into Identity Manager, the utility supports three types of registries used by Access Manager: LDAP Directory, Active Directory and Domino Directory. The Identity Manager to Access Manager Synchronization solution supports only LDAP as the Access Manager registry. Also, the LDAP changelog must be enabled.

These utilities have been made as automated as possible. For example, when retrieving user data from Access Manager, an extra connector is used to find the Access Manager user index first and then a second connector retrieves the attributes. This way, user input for the search base is not required. In synchronization, monitoring the changelog ensures that the connector automatically detects all the Identity Manager user attribute changes.

Performance
The performance of the utility mainly depends on Directory Integrator. However, the algorithm and error handling of the utility influences the performance too. The error dumping should be turned on only for debugging because it has a large performance impact.

Security Concerns
1.Secure the configuration file and customer settings.
The administrator can set the password for the configuration file and select the encryption option for the properties files.

2.Enable SSL between the directory and Directory Integrator.
The communication between the directory and Directory Integrator can be SSL enabled. For more detail, consult the IBM Directory Integrator 5.1.2 Reference manual.

3.Enable SSL between Directory Integrator and Identity Manager.
The communication between Directory Integrator and Identity Manager can be SSL enabled. For more detail, consult the Identity Manager 4.5 Server Configuration manual.

Configuration File Examples

TAMtoTIMImport.xml
The task of this configuration file is to search Access Manager users in a single domain, import Access Manager user data to Identity Manager, and create Identity Manager persons. Three AssemblyLines are built into this configuration file.

This AssemblyLine retrieves Access Manager user data from LDAP registries, like IBM Directory, Sun ONE (formerly iPlanet) Directory, and so on.

The first connector works in Iterator mode. It searches the cn=users entry under secAuthority=Default. The search filter is defined as objectClass=secMap. Each returned record contains the secdn attribute, which is the user's dn that Access Manager recognizes.

With the secdn attribute obtained from the first connector, the second connector works in lookup mode and searches the dn matching the secdn. If found, it retrieves cn, sn, uid, and other attributes. During this process, it uses the “ After Lookupâ€_ user exit feature of Directory Integrator to run a JavaScript in order to exclude the Security Master user:

                    var tdn=conn.getString("$dn");

                    if (tdn.indexOf("SecurityMaster",0) > 0)

                      system.skipEntry();

                    else

                      task.logmsg("---> Access Manager user data is read." + tdn);

            

This JavaScript can be modified to exclude more specific users, so that modification of any of these Access Manager super users.

The third connector, as is common in the other AssemblyLines, is for Identity Manager importing. This connector is a JNDI connector and works in AddOnly mode. The details for using the DSMLv2 support in Identity Manager 4.5, including the JNDI connector settings can be found in the Identity Manager 4.5 Policy and Organization Administration Guide.

This connector takes the work attributes from the previous connectors and maps them to the following Identity Manager attributes:

cn, sn, objectClass, displayName, givenName, uid, erAliases.

The first three are Identity Manager required attributes. An Identity Manager user cannot be created if any of them are missing. The Identity Manager or Access Manager administrator can also provide a customized attribute mapping schema or the administrator can modify the current mappings, which can be done through the Directory Integrator admin tool.

The erAliases is a multi-value variable, which is mapped from the Access Manager uid and cn. This attribute is for Access Manager account reconciliation after the Identity Manager person is created.

This AssemblyLine retrieves Access Manager user data from the Active Directory registry. Currently, only the Active Directory in the Windows 2000 server is supported by Access Manager.

Similar to the previous AssemblyLine, the first connector, FindADTAMUsers, works in Iterator mode and searches all the Access Manager users from Active Directory in the customer domain. The administrator needs to provide the active directory domain name for the search base. With the domain name as “domain_nameâ€_, the search base is:

cn=Users,cn=default,cn=tivoli pd domains,dc=domain_name,dc=com

The search filter is:

objectCategory=cn=urafuser,cn=schema,cn=configuration,dc=domain_name,dc=com

Each returned record contains the urafregistryUID attribute, which is the user’s dn in Access Manager.

Then the second connector GetADTAMUsers looks up the directory to find the dn that equals the urafregistryUID and retrieves the user attributes for importing into Identity Manager. Also, if the dn being searched is “sec_masterâ€_ or “ivmgrd-masterâ€_, the entry is skipped.

The third connector in this AssemblyLine is for Identity Manager importing, which is the same as in the previous AssemblyLine.

This AssemblyLine retrieves Access Manager user data from a Domino server directory.

The first and the second connectors in this AssemblyLine are Lotus Notes connectors, which interact with the Domino directory through the local Notes client. The first connector searches the PDMdata.nsf database on the Domino server and the database view is set to URAF User Objects. Each returned record contains the UserID attribute, which represents an Access Manager user.

The second connector looks in the names.nsf database in the Domino directory to find the ShortName matching the UserID obtained from the previous connector. When found, the connector retrieves the First name, Last name, and so on, as the input working attributes for the AssemblyLine. In order to avoid modification of the Access Manager administrator accounts, a JavaScript filter is used to exclude the Access Manager administrator.

The third connector is for Identity Manager importing, which is the same as in the previous AssemblyLine.

MDTAMtoTIMImport.xml
Because Access Manager supports multi-domain users only in an LDAP Directory, this configuration file contains only one AssemblyLine to retrieve Access Manager users in multi-domanis from the LDAP registry and import them into Identity Manager.

The first connector searches the cn=Subdomains under secauthority=default. The search filter is secmap. The cn=Users is further checked from each returned object dn. If “cn=Usersâ€_ is not found, the entry is skipped. Also, if the dn is the Security Master, the record is skipped. The final records returned from this connector include Access Manager users from all the domains. If you do not want to import from all the domains, the Java Script under hooks can be modified to exclude those unwanted domains.

After the search in multi-domains, the second and third connectors work the same way as in the single domain AssemblyLine.

DirectorytoTIMImport.xml
This configuration file contains two AssemblyLines: LDAPUserstoTIM and ADUserstoTIM. The first one retrieves the user data from a corporate LDAP directory while the second one retrieves user data from Active directory.

Because user attributes in each corporate registry might be very different, the utility sample provided is very basic. It retrieves only cn, sn, and uid attributes, maps them to the corresponding Identity Manager user attributes for Identity Manager user creation. More attributes can be easily added by modifying the Input Map and Output Map of the connectors in the AssemblyLine.

The connectors in each AssemblyLine are very similar to TAMtoTIMImport.xml. However, the search base has to be manually defined.

TIMtoTAMSync.xml
This configuration file is used to synchronize Identity Manager user attributes with Access Manager user attributes. The synchronization is designed for those Access Manager users who have Identity Manager accounts. Two AssemblyLines are built in this configuration file. The first AssemblyLine is for unconditional synchronization and the second AssemblyLine is to monitor the LDAP changelog and start the synchronization dynamically. The second AssemblyLine is introduced here.

One thing to note about this task is that it presumes that its users understand how the Identity Manager and Access Manager user registries are organized. This task has been developed to work with Identity Manager 4.5 and Access Manager 4.1 or 5.1. Future releases of these products may change how they organize their user registries, thereby requiring modification of this task in order for it to continue working.

AssemblyLine: synctambychangelog
This AssemblyLine monitors the Identity Manager user attribute changes from the LDAP changelog. To use this AssemblyLine, the LDAP changelog must be enabled. The AssemblyLine updates the matched Access Manager user data if the Identity Manager user attributes are changed. The AssemblyLine can be started manually anytime or, by the ScheduleSync event handler, at the scheduled time.

Starting from the last change number defined in the TIMtoTAMSyncExit file, the first connector reads the changelogs. The last change number is updated each time the AssemblyLine is run.

The first task for this connector is to filter out the non-Identity Manager user changes. Each LDAP changelog contains a targetdn, which is the dn of the changed entry. If this dn starts with "ERGLOBALID or "ergloblid", it is the Identity Manager user changes. If not, the change log is skipped.

Working in Lookup mode, the second connector searches Access Manager accounts under the Identity Manager directory suffix. Each Access Manager account has an owner who is an Identity Manager user. The AssemblyLine’s task is to find those Access Manager account owners who were found in the previous connector. The connector does this by comparing the “ erprentâ€_ attribute in each Access Manager account to find one that equals the “targetdnâ€_ attribute found in the previous connector. If they are matched, both the Access Manager account and its owner, who is an Identity Manager user with his user attributes changed, are located. Also, the Access Manager account’s attribute, ertamdn, is retrieved which is the correspondent Access Manager user dn. Now we have the Identity Manager user’s dn and the Access Manager user’s dn. This connector is a key connector.

The third connector now looks up the Identity Manager dn, which is equal to the “erparentâ€_ working attribute and, retrieves the user attributes to add to the working attributes. The retrieved attributes are those business and personal attributes defined such as postal address, telephone number, and so on.

After this, the last connector works in Update mode. It looks up the Access Manager dn that matches the “ertamdnâ€_ attribute found in the second connector. The connector defines the maps between the Identity Manager personal and business attributes and Access Manager ones. It modifies all the defined attributes in Access Manager registry.

Timer Event Handler (EH): ScheduleSync
This event handler is used to control the start time of synctambychangelog AssemblyLine. The reason for building this timer event handler is to provide the administrator with a tool to start the AssemblyLine periodically rather than running continuously. This EH is simply a timer so the administrator can define the AssemblyLine start time in any format (hourly, daily, weekly, and so on). Also, the options for the changelog connector define the sleeping time and waiting time. Selecting different combinations gives the administrator flexibility for the business needs. The start time, sleeping time, and waiting time can be defined in the properties file.

Exit file: TIMtoTAMsyncexit
The exit file contains the changelog start number. The changelog start number tells the AssemblyLine where in the changelog to start looking for Identity Manager user modifications. Providing the start number prevents the AssemblyLine from continually synchronizing old user attributes changes, which have already been synchronized previously.

The default starting number can be set in the file. After the first execution, the AssemblyLine updates the starting number dynamically each time the changelog is processed.

Running the utility

Where to install?
These solutions can be installed on any server or workstation in the corporate intranet. The only prerequisite is Directory Integrator 5.1.2. Directory Integrator can remotely interact with different data resources. If the Lotus Notes connector is used to access user data in the Domino server, Directory Integrator and its utility files should be installed together with the Notes client.

What needs to be done before running the utility?

• Define the environment settings in the properties file.
• Create an IDI Data Feed service in the Identity Manager 4.5 server. User ID, Password and NamingCon text must be defined in the Identity Manager server and put into the properties file for the Directory Integrator JNDI connector to use.
• Before running on the production server, run a “Proof of Conceptâ€_ test first in a simulated environment to check the properties file settings, output results, and so on. The test should be run using the Directory Integrator Administration Tool. In the Administration Tool, you can try to connect to the data source and see if the connection can be established. During the execution, check for any errors. If an error occurs, turn on the error dump. You can then view the detail error logs in the Admin Tool.

How to execute the Directory Integrator utility?

• To start an AssemblyLine from the Directory Integrator Admin Tool. Start Directory Integrator Admin Tool and load the configuration file. Select the AssemblyLine or EventHandler for the task. Click the “runâ€_ button in the upper right corner. Information about the run shows in the execution window. An example of Directory Integrator Admin Tool is shown in Figure 1.

Figure 1: Directory Integrator Admin Tool

• To start an AssemblyLine from the command line.

At a command line prompts:
Change directories to the Directory Integrator root directory (for example, C:\Program Files\ibm\IBMDirectoryIntegrator).
Type the following command to start the Directory Integrator with the defined configuration file and the AssemblyLine:
ibmdisrv -c"Configuration file name " -r"AssemblyLine nameâ€_ -w

Note: Directory Integrator console option
With the “-mâ€_ option, you can start the Administration and Monitor Console. The Console, when enabled, lets the administrator manage and monitor the AssemblyLines using a browser. The administrator can view and manage the status of the running AssemblyLines. The default URL address is: http://server_ip_address:8989 . An example of the Administration and Monitor Console is shown in Figure 2.

Figure 2: Directory Integrator Administration and Monitor Console (AMC)

How to check the execution results?
Messages
View the execution messages in Directory Integrator Admin Tool UI and turn on the error dumps.
The Error hooks in the utility, by default (for performance purposes), are defined as:"system.skipEntry();"
For error analysis, it should be changed to: "system.dumpEntry(error);"

• Output files - Enable the FileOutput connector in each AssemblyLine to examine the final attribute values from the output files.
• Check the user data directly Through LDAP, Active Directory, Domino Server, check the user data to see the importing or synchronization results.
• Check the results from Identity Manager server - See if the user importing process is successful.

References
For a quick overview and start of Directory Integrator:
IBM Directory Integrator 5.1.2: Getting Started manual

For information on installing and configuring of Directory Integrator:
IBM Directory Integrator 5.1.2: Reference manual

For information about configuring the IDI Data Feed in IBM Tivoli Identity Manager:
IBM Tivoli Identity Manager 4.5: Policy and Organization Administration Guide

What do you think of this document? Killer! (5) Good stuff (4) So-so; not bad (3) Needs work (2) Lame! (1) Comments?

developerWorks > Tivoli