Debugging and troubleshooting the IBM Tivoli Directory Integrator Windows Password Synchronizer Plug-in

This article primarily focuses on IBM® Tivoli® Directory Integrator Password Synchronizer Plug-in for synchronizing Microsoft® Windows® Active Directory with Tivoli Directory Server 6.0 using IBM Tivoli Directory Integrator 6.1.1. In this example, we use MQ Everyplace as a password store, and we also discuss LDAP password store.

Mukesh K Singh, Systems Software Engineer, IBM Software Labs, India

Mukesh SinghMukesh is working with Tivoli Security L2 Support team in IBM India, Pune. He has over two years of experience and his areas of interest are IBM Tivoli Directory Integrator and IBM Tivoli Directory Server

Yogesh S Talekar, Principal Software Engineer, IBM Software Lab, India

Yogesh TalekarYogesh is working with Tivoli Security L2 Support team in IBM India, Pune. He has over eight years of experience and his areas of interest are IBM Tivoli Directory Server, IBM Tivoli Directory Intergrator and oprating systems.

21 July 2008


Password synchronization is required in network-enabled infrastructures to ease user tasks in maintaining uniform passwords on many heterogeneous systems with multiple login accounts. This helps users to have uniform passwords across multiple systems, which can include one or more flavours of LDAP servers, Active Directory domain server(s), Web Access Managers, Operating Systems Access Managers, and even Identity Managers. A password synchronization solution built with the IBM Tivoli Directory Integrator (TDI) can intercept password changes that happen on a number of systems and redirect the changes back into the same software systems or to a different set of systems. The main security objectives of password synchronization are to:

  • Help users keep uniform passwords on all systems, which means they do not have to remember different passwords
  • Control password strength across all platforms in a uniform fashion
  • Centrally manage expiry of passwords on all systems
  • Facilitate delegation of administrative tasks involved in password management

The IBM Tivoli Directory Integrator provides an infrastructure and a number of ready-to-use components for implementing solutions that synchronize user passwords in heterogeneous software environments. A password synchronization solution built with the IBM Tivoli Directory Integrator can intercept password changes on a number of systems. The intercepted changes can be directed back into the same software systems or a different set of software systems. Synchronization is achieved through the IBM Tivoli Directory Integrator AssemblyLines, which can be configured to propagate the intercepted passwords to desired systems. The information on these different plug-ins is in the Password Synchronization Plug-ins Guide available online.

One of the widely used password plug-ins is the Tivoli Directory Integrator Windows Password Synchronization Plug-in. The Password Synchronizer for Windows intercepts password changes of user accounts on Windows operating systems and redirects them to the same system or different software systems. The installation and configuration instructions are in the same Password Synchronization Plug-ins Guide available online.

In this article, we discuss frequent problems you face when installing and configuring the TDI Windows Password Plug-in Synchronizer and how to troubleshoot these problems.

Active Directory and Tivoli Directory Server (TDS) in a typical corporate environment

In a typical networked IT infrastructure, assume that you have already installed an Active Directory on Windows 2003 servers and you are using Active Directory domain for your desktop authentications. You may be using Active Directory to control access to your file servers, printers, and other IT infrastructure as well. In addition, there are situations where you might also have other software components to enforce controlled access to Web and operating system resources. Such software typically use directory server software that run the LDAP protocol as a back-end for storing user data as well as policy data. IBM Tivoli Access Manager for e-Business (TAM-eB) and IBM Tivoli Access Manager for Operating Systems (TAM-OS) are good examples of such software. Both the products make use of IBM Tivoli Directory Server to maintain user- and policy-related data. IBM Tivoli Access Manager for Business Integration (TAM-BI) and IBM Tivoli Identity Manager (ITIM) also make use of LDAP back-end servers.

In such complex environments, it is possible that your usual desktop users have accounts on Active Directory and some of those users also have accounts on ITAM or ITIM, which actually store the data on back-end LDAP server(s). In this article, we assume these accounts are actually present in the IBM Tivoli Directory Server (TDS) back-end.

A chaotic situation can occur in a scenario where two or more flavours of LDAP server are used to register the same users multiple times and their account management is done separately on different systems. IBM Tivoli Directory Integrator (TDI) can greatly reduce administrative overhead by synchronizing your Active Directory domain accounts with Tivoli Directory Server (TDS) by using its password synchronizing plug-ins.

The following figure explains a typical set up and flow of data when a Tivoli Directory Integrator (TDI) server is configured with Password Synchronizer Plug-in. TDI is used to synchronize data between a Microsoft Active Directory and IBM Tivoli Directory Server.

Figure 1. TDI Password Plug-in set up with data flow

TDI Password Plug-in set up with data flow

When the Tivoli Directory Integrator (TDI) is configured with the Password Plug-in successfully, it intercepts all the password changes and account changes going towards the Active Directory. Further, the changes are synchronized with the corresponding account on the Tivoli Directory Server (TDS) server. In addition, if there is a new account added on the Active Directory, it will be added to the Tivoli Directory Server (TDS) server through the Tivoli Directory Integrator (TDI) Password Synchronizer Plug-in.

The following diagram shows a detailed picture of data flow sequence for the scenario explained above.

Figure 2. TDI Password Plug-in - data flow sequence

TDI Password Plug-in - data flow sequence

Password Synchronizer and related TDI terminology

Password Synchronizer is a component deployed on Windows Active Directory that intercepts plain (unencrypted) values of passwords as they are changed

Password store is a Tivoli Directory Integrator (TDI) component that receives the intercepted passwords, encrypts, and stores them in locations that can be accessed by the IBM Tivoli Directory Integrator (TDI). Two types of password stores are available in Tivoli Directory Integrator (TDI): MQ Everyplace and LDAP.

Connectors are either standard or specialized IBM Tivoli Directory Integrator connectors. They connect to locations where the intercepted and encrypted passwords are stored and are able to retrieve and decrypt the passwords.

MQ Everyplace password store

MQ Everyplace (MQe) password store facilitates the secure propagation of the changes to the IBM Tivoli Directory Integrator where it can be manipulated by an IBM Tivoli Directory Integrator AssemblyLine.

LDAP password store

The LDAP password store is available for the following directory servers:

  • IBM Tivoli Directory Server
  • Microsoft Active Directory
  • Sun ONE Directory Server

Differences between LDAP and MQe password stores

The LDAP password store maintains the state of the user's passwords. It keeps the passwords in the LDAP storage entries up-to-date with the passwords of the corresponding user. In contrast, the MQe password store does not maintain the state of the user's passwords and just reports the changes. In MQe password store, each message details how the passwords of a user have changed ane not what the user's actual password values are.

This difference is important for the design of the Tivoli Directory Integrator (TDI) AssemblyLine that propagates the password changes to other systems, especially when multiple valued passwords are supported. When an LDAP password store is used, the AssemblyLine must replace the passwords in all systems that it keeps synchronized with the passwords read from the LDAP password store.

When an MQe password store is used, the AssemblyLine must duplicate only the reported password change on the other systems. Each MQe message contains the following information:

  • User identifier: This is a string that identifies the user on a target system (DN or user account name). The AssemblyLine must locate the users on the systems, which are synchronized based on this user identifier
  • Type of the password modification (add / delete / change/ replace): If the target system does not support multiple passwords for a single user, the type is always "replace". "Add" and "delete" make sense only when multiple password values are supported by the target system
  • A list of password values

Troubleshooting and debugging typical problems with the Password Synchronizer Plug-in

This section describes some of the commonly faced problems and solutions with Tivoli Directory Integrator (TDI) Password Synchronizer Plug-in.
Note: Make sure you have applied FP1 on Tivoli Directory Integrator (TDI) version 6.1.1. This basically ensures that you do not face any problems with MQe password store connector.

1. Problem with absolute path size restriction on Windows Password Synchronizer Plug-in (server1 in Figure 1)

If the Windows Password Synchronizer Plug-in is installed inside a system directory where the absolute path is longer than 37 characters, (For example C:\Program Files\UserDirectory\IBM\DiPlugins\V6.1 ), then the plug-in will hang when the Active Directory Domain controller is restarted.

Solution :
Avoid installing the plug-in in a directory where absolute path exceeds 37 characters. Try to choose shorter directory names and paths.

2. Verifying Registry Settings in Windows after password plug-in is installed (Server1)

When you install the Tivoli Directory Integrator (TDI) Password Synchronizer Plug-in check your operating system's registry again and make sure that the installation is successful.
The IBM Tivoli Directory Integrator Password Synchronization Plug-in Installer creates the following registry entries in the key folder:

HKEY_LOCAL_MACHINE\SOFTWARE\IBM\Tivoli Directory Integrator 6.1.1\Windows Password Synchronizer
The following keys must exist with the corresponding value:
Class: REG_SZ:
Classpath: REG SZ: c:\install_directory"
Java:REG_SZ: "c:\install_directory\jvm\jre\bin\java.exe"

Registry settings

3. Active Directory and security policies. (Server1)

When you install Active Directory on the Windows 2003 server, the Local Security Policy menu disappears from the Administrative Tools. This is because the Local Security Policy is replaced with two new policies, the Domain Security Policy and the Domain Controller Security Policy.

The Domain Security policy applies to all the users and objects that are part of the Active Directory domain, which can include desktop users, file servers, and printers. The Domain Controller Security Policy is applicable to all the Windows 2003 servers that have Active Directory installed and are playing the role of additional or child domain controllers in that domain. Therefore, whenever there is a reference to Local Security Policy in the documentation, it should be replaced by the Domain Security Policy in case you are using it in a context which is specific to Windows Active Directory server.

When you complete the required configuration on Windows, you are ready to setup MQEveryplace Password Store on server1 in Figure 1. Follow instructions from TDI Plug-ins Guide to install and configure MQe Password Store.

Files named idicryptokeys.bat, mqeconfig.jar and mqeconfig.props are automatically created by Password Synchronizer after installation on Windows Active Directory Server. See the screenshot for an example.


The following screenshot shows an example of mqeconfig.props file on the Windows 2003 server (server1 in figure 1) where the password plug-in is installed.


4. java class not found error while configuring MQe Password store. (server1 in figure 1)

If the following command is used to automatically configure MQe QueueManager for the Storage Component
> C:\Program Files\IBM\DiPlugins\V6.1.1\jvm\jre\bin>java -cp "./mqeconfig.jar" mqeconfig.props create client
It throws exception: The java class is not found:

The following screenshot shows this error:

Solution :
Ensure that the following .jar files are manually copied from the Tivoli Directory Integrator (TDI) Windows Password Synchronizer default installed location "C:\Program Files\IBM\DiPlugins\V6.1.1\IDI\jars" to "C:\Program Files\IBM\DiPlugins\V6.1.1\jvm\jre\lib\ext"

If you have configured the password store to this point and have resolved all the issues mentioned above, then you can restart the Windows 2003 Active Directory server (server1 in Figure 1) only if your Tivoli Directory Integrator (TDI) server (server2 in Figure 1) is already configured. If not then, you must refer to the Plug-in Guide document and configure the Tivoli Directory Integrator (TDI) server for MQe password store (Server2).

After this section, we refer to problems that are faced on the server where Tivoli Directory Integrator is installed (Server2).

5. Problem: CTGDIS696E error is thrown while connecting to data source using MQe Password Store Connector (server2 in Figure 1)

Snapshot of the error message:

Snapshot of the error messageSolution:
This problem is specific to Tivoli Directory Integrator (TDI) 6.1 and Tivoli Directory Integrator (TDI) 6.1.1, and it is related to the new feature called systemqueue.on

File ( files:
## System Queue settings
## If set to "true" the System Queue is initialized on startup and can be used;
## otherwise the System Queue is not initialized and cannot be used.

By default, this property is set to "false". Ensure that this parameter is set to "true" in the (or file. Also ensure that the MQ Everyplace queues are properly configured.

6. Problem: Error while changing user password or adding a new user on Active Directory server (server1 in Figure 1)

First make sure that your passwords meet the complexity criteria given in the password policies. If you are sure that the password is complex enough, then it might be a problem related to overall configuration of Password Plug-in and password store.

Make sure you have configured the Password Store on the Windows Active Directory server and Tivoli Directory Integrator (TDI) server before rebooting the Active Directory server.

7. Tivoli Directory Integrator (TDI) server is not able to iterate the queues and throws an error saying that the queue is not ready.

If Tivoli Directory Integrator (TDI) connector is not able to iterate over the queue, it means that settings in the and files for queue and ini files are not correct.
Recheck that the following section is (

### MQe JMS driver initialization properties
## Specifies the location of the MQe initialization file.
## This file is used to initialize MQe on TDI server startup.
systemqueue.jmsdriver.param.mqe.file.ini=C:\Program Files\IBM\TDI\V6.1.1\MQePWStore\pwstore_server.ini

Debugging Password Synchronizer for IBM Tivoli Directory Server while using LDAP Password Store

If Tivoli Directory Server (TDS) is configured as the LDAP Password Store and TDS fails to start with the error "Fail to load plugin from C:\Program Files\IBM\DiPlugins\IDS\pwsync.dll", some of the typical reasons are:
(1) idipwsync.props file is not configured properly
(2) Schema modifications are not applied to the LDAP Password Store

Make sure the configuration steps are completed appropriately. Some important configuration steps are listed below:
1. Ensure configuration settings in the 'idipwsync.props' file are correct. A sample idipwsync.props file is listed below:

#IDI LDAP Password Store Settings with Encoded Passwords
#Fri Sep 14 18:37:29 IST 2007
logFilePath=C:\\Program Files\\IBM\\DiPlugins\\IDS\\IDSPWSync\\idipwsync.log

Make sure that in the above configuration file the logFilePath is specified using '\\' instead of '\'. To enable SSL and encryption, the parameters encrypt and SSL must be set to true and the corresponding keystore or truststore files must be specified.

2. Make sure you have modified the schema appropriately. Define the ibm-diPerson object. From a machine with Tivoli Directory Server (TDS) (Password Store), issue the following command from the TDS install_directory:
> ldapmodify -c -h LDAP Hostname -D admin DN -w adminpassword -f ibm-diPerson_oc.ldif

If you are still getting additional issues, follow the appropriate logs and trace files for problem determination.

Logging and tracing :
After enabling security policy on Active Directory and as soon as you reboot your system for policies to be effective, it creates three traces on the C:\ drive
- C:\PWFLTTC.trc, which contains trace messages generated while the Windows Password Synchronizer is being initialized
- C:\PWFLTOUT.trc, which contains Information and Diagnostic trace information
- C:\PWFLTERR.trc, which contains Warning and Error trace information

Other useful logs are in following files on the C:\ drive:
- ProxyAuth.trc
- PWFLAuth.trc
- mqpwstore.log
- pwsync_admin.log

Debug logs and traces that must be sent to support for assistance

The following logs and traces must be sent to IBM Customer Support Team, so that problems related to the Password Synchronizer Plug-in can be quickly identified and resolved.

Logs to be collected from the Windows 2003 Active Directory Server where Password Synchronizer Plug-in is installed are:

  • PWFLTC.trc
  • PWFLTERR.trc
  • PWFLTOUT.trc
  • ProxyAuth.trc
  • PWFLAuth.trc
  • mqpwstore.log
  • pwsync_admin.log
  • Windows 2003 Server error logs that are found in Administrative Tools -> Event Viewer under the tabs: Directory Service and Security

Logs to be collected from the server where Tivoli Directory Integrator (TDI) is installed:

  • ibmdi.log

Logs to be collected from the server where Tivoli Directory Server (TDS) is installed:

  • ibmslapd.log
  • audit.log (if audit logging is enabled)
  • adminaudit.log (if audit logging is enabled)



Get products and technologies

  • Download IBM product evaluation versions and get your hands on application development tools and middleware products from DB2®, Lotus®, Rational®, Tivoli®, and WebSphere®.



developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into Tivoli (service management) on developerWorks

Zone=Tivoli (service management), Security
ArticleTitle= Debugging and troubleshooting the IBM Tivoli Directory Integrator Windows Password Synchronizer Plug-in