Deployment and Configuration

IBM Tivoli Directory Integrator

Deployment and Configuration

Post-install configuration

Follow these steps to register the Password Synchronizer for password change notifications:

Copy the DLL of the Windows Password Synchronizer to the System32 folder of the Windows installation folder. Note that on 64-bit Windows operating systems, the 64-bit DLL of the Password Synchronizer must be put in the System32 folder.
List the name of the Windows Password Synchronizer DLL (without the ".dll" file extension) in the "HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\LSA\Notification Packages" Windows registry key (see the following section, Configuration parameters in the Windows registry). Make sure you put in the name of the 64-bit DLL on a 64-bit Windows platform.
Execute the registerpwsync.reg file, which is shipped with the Password Synchronizer. This will create a key for the Windows Password Synchronizer in the Windows registry: "HKEY_LOCAL_MACHINE\SOFTWARE\IBM\TDI\Windows Password Synchronizer". It will also set a string value "ConfigFile" that contains the absolute file name of the configuration file of the Windows Password Synchronizer.

Configuration parameters in the Windows registry

This plugin must be registered in the Windows LSA for receiving password changes notifications. For this purpose the name of the external library must be registered in the specific registry key. Additionally the external library file should be placed in one of the directories that is specified by the PATH environment variable. After this procedure is completed the operating system must be restarted so the external library can be loaded.

If the external library file is registered but could not be loaded successfully for some reason then the Windows OS might become unstable.

When the native module of the Windows Password Synchronizer is initialized, it will read from the registry key folder:

[HKEY_LOCAL_MACHINE\SOFTWARE\IBM\TDI\Windows Password Synchronizer]

The following registry key is of vital importance, because it contains the location of the configuration file of the Password Synchronizer:

Table 2. Primary registry key

Key name Type Description Required?

ConfigFile REG_SZ This key specifies the full path of the configuration file of the Windows Password Synchronizer. true

Key name	Type	Description	Required?
ConfigFile	REG_SZ	This key specifies the full path of the configuration file of the Windows Password Synchronizer.	true

Below is a list of optional registry keys which affect the behavior of the Windows Password Synchronizer. You should not set these manually - use the Administration Tool instead.

Table 3. Optional registry keys

Key name Type Description Default Required?

disabled REG_SZ This key specifies whether the password change should be propagated to the Java Proxy process. false false
reconfigure REG_SZ This key specifies whether the plugin should reload its configuration file on the next password change notification. false false

Key name	Type	Description	Default	Required?
disabled	REG_SZ	This key specifies whether the password change should be propagated to the Java Proxy process.	false	false
reconfigure	REG_SZ	This key specifies whether the plugin should reload its configuration file on the next password change notification.	false	false

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\LSA

The following key should be present:

Table 4. Optional registry keys

Key name Type Description Default Required?

Notification Packages REG_MULTI_SZ This key specifies the external libraries to register for notifications. unknown true

Key name	Type	Description	Default	Required?
Notification Packages	REG_MULTI_SZ	This key specifies the external libraries to register for notifications.	unknown	true

Do not delete any of the values of this key. Put the name of the library on the last line. Do not include the .dll extension to the name you enter.

Reboot the Windows machine so that the changes can take effect.

Configuration parameters in the configuration file

The configuration file is named pwsync.props. Many of the configuration parameters in this file are common to all Password plug-ins, see Configuration file parameters.

The list below describes only those parameters that are specific to the Windows Password plug-in.

includeGroups

An optional list of Windows groups. If a user is a member of any group in the list, the user will be accepted by the user filter (assuming the user is not excluded by any of the exclude lists).

excludeGroups

An optional list of Windows groups. If a user is a member of any group in the list, the user will not be accepted by the user filter.

includeDNs

An optional list of DN suffixes. If a user's Distinguished Name matches any suffix on the list, the user will be accepted by the user filter (assuming the user is not excluded by any of the exclude lists).

excludeDNs

A list of DN suffixes. If a user's Distinguished Name matches any suffix on the list, the user will not be accepted by the user filter.

accountTypes

This property specifies the type of the account for which password changes will be reported. Its format is a space-delimited list of account types.

The Password Synchronizer plug-in is capable of reporting password changes to the following Windows account types:

NORMAL_ACCOUNT: This is a default account type that represents a typical user.
TEMP_DUPLICATE_ACCOUNT: This is an account for users whose primary account is in another domain.
INTERDOMAIN_TRUST_ACCOUNT: This is a permit to trust account for a domain that trusts other domains.
WORKSTATION_TRUST_ACCOUNT: This is a computer account for a computer that is a member of this domain.
SERVER_TRUST_ACCOUNT: This is a computer account for a backup domain controller that is a member of this domain.

An example value for this key would be:

"NORMAL_ACCOUNT WORKSTATION_TRUST_ACCOUNT"

The Password Synchronizer always reports password changes to accounts of type NORMAL_ACCOUNT regardless of whether NORMAL_ACCOUNT is specified in the AccountTypes parameter.

Enabling Local Security

Change the Local Security Policy as follows:

Select Control Panel>Administrative Tools>Local Security Policy
Select Account Policies>Password Policy
Change Passwords must meet complexity requirements to enabled.

Notes:

For this change to take place, reboot the machine. Make sure that you set up the Password Store properties file before rebooting the machine.
If the Windows Server is configured as a Domain Controller, the "Passwords must meet complexity requirements" setting needs to apply to the whole Active Directory Domain, therefore this setting should be modified using the "Domain Security Policy" tool.

Password Stores setup information

The installer will configure the Password Synchronizer to use the Log Password Store by default.

For information on setting up the Password Stores, see the following resources:

Plug-in administration tool

A command line tool for performing administrative tasks, pwsync_admin.exe, can be found in the plug-in installation directory. The primary purpose of this administrative tool is to allow reconfiguration of the Windows Password Synchronizer without rebooting the Windows machine. For example, this tool enables changing of the password store without rebooting Windows.

The only change that cannot be accomplished without rebooting Windows is replacing the tdipwflt.dll plug-in, located in the Windows System32 directory.

Usage

This is how the administration tool is used from the command line:

pwsync_admin.exe - command for 32 bit Windows
pwsync_admin_64.exe - command for 64 bit Windows

This tool takes a single command line parameter (the command argument above), which can have one of the following values:

suspend_plugin: This command writes a boolean value to the Windows registry (please see the Windows registry settings section), thus indicating to the plug-in that subsequent password changes must not be propagated to the Java™ proxy. This command causes subsequent password changes to be skipped until a resume_plugin command is issued.
resume_plugin: This command writes a boolean value to the Windows registry (please see the Windows registry settings section), thus indicating to the plug-in that subsequent password changes must be propagated to the Java proxy. This command causes subsequent password changes to be synchronized until a suspend_plugin command is issued.
reconf_plugin: This command writes a boolean value to the Windows registry (please see the Windows registry settings section), thus indicating that the plugin must reload its configuration file. Reloading will not happen immediately but rather on the next password change. This means that if there are any errors with the new configuration, they will not become evident immediately. We could trigger a password change of a test account to enforce the reconfiguration. Beware that reconfiguration will be postponed if the plugin is suspended.
query_plugin: This command queries the status of the plugin - whether the plugin is currently loaded and if its last initialization was successful.
stop_proxy: This command causes the administration tool to connect through a socket to the command socket port of the Java proxy and send a stop request to the proxy. This causes the proxy to terminate gracefully.
start_proxy: This command starts the Java proxy, which causes the proxy configuration to be reloaded.
restart_proxy: This command is equivalent to a stop_proxy command followed by a start_proxy command.
query_proxy: command determines whether the Java Proxy is running or not.

Operational Windows registry settings

There are a number of Windows registry keys associated with the Windows Password Plug-in and its operations:

Enable or disable plugin

The registry key used by the suspend_plugin and resume_plugin commands is:

[HKEY_LOCAL_MACHINE\SOFTWARE\IBM\TDI\Windows Password Synchronizer] "disabled"="true"

If the key has a value of true, then the plug-in will not synchronize passwords. If this key is missing or has a value other than true, the plug-in will synchronize passwords. This key is created by the plug-in administration tool on first use.

Reload plugin configuration

The reconf_plugin command uses the following registry key:

[HKEY_LOCAL_MACHINE\SOFTWARE\IBM\TDI\Windows Password Synchronizer] "reconfigure"="true"

If the key is set to true, then on the next password change the plugin will reload its configuration file. The plugin will also change the value to "false", so that the reload happens only once.

Neither of the above keys is present in the Windows registry after the plug-in is installed. These keys are not required for the normal operation of the plug-in.

Logging

The administrative tool logs messages both to the console and to a log file named pwsync_admin.log, which is located in the install directory of the plug-in. The log file can be used for analyzing errors encountered during administrative tool operations, or an historical reference for operations performed using this tool.

Considerations when using the administration tool

When using the administration tool, be aware of the following considerations:

When the plug-in is suspended, password changes are skipped (not propagated) by the plug-in. This can result in inconsistencies (password changes lost) in the target synchronization system
The plug-in will attempt to restart the Java proxy only if reconfiguration is requested (see the "reconf_plugin" admin tool command) and the proxy is not already running.
When the Java proxy is started, it loads the password store configuration file. This happens when the machine is rebooted, or when the plug-in is not suspended but the Java proxy is stopped as a password change occurs. If the user is editing the configuration file at the time, the Java proxy may load a possibly corrupted configuration.
When the plug-in is not suspended and the Java proxy is not running, if a password change is issued with the Active Directory Users and Computers user interface tool, the plug-in is notified by Windows two or three times of this password change. The result is that the same password update is propagated two or three times. This happens because the plug-in starts the proxy on the next password change, which takes some time. This causes Windows to notify the plug-in several times of the same password change. This multiple reporting, however, is only present the first time the Java proxy is not running, because on subsequent password changes the Java proxy is already running.
When the plug-in is configured with the LDAP Password Store and the LDAP Store itself is set for asynchronous storing (waitForStore=false specified in the LDAP Store configuration file), and when the plug-in is not suspended, it is possible that a stop_proxy command would cause some password changes to be skipped.

The following recommendations help address these problems:

Suspend the plug-in using a suspend_plugin command prior to any stop_proxy or restart_proxy commands.
Make a copy of the configuration file for editing purposes. Replace the old configuration file with the new one when all edits are complete.
Make any necessary configuration changes at a low usage time, so that few (if any) password changes will be skipped and not propagated.

Example for changing the configuration without rebooting the Windows machine

The following steps show how the configuration settings can be changed without rebooting the Windows machine:

After these steps are completed the plugin, the Java proxy and the password store will use the new configuration settings. During the short window when the plug-in is suspended, however, password changes could be skipped. They will occur in the Windows domain controller, but they will not be propagated by the plug-in. Therefore, this procedure should occur at a low usage time, when password changes are unlikely.

Copy the configuration file to a temporary location.
Edit the file in this temporary location.
Copy the edited file back to the original location.
Run the pwsync_admin.exe suspend_plugin command.
Run the pwsync_admin.exe reconf_plugin command
Run the pwsync_admin.exe stop_proxy command.
Run the pwsync_admin.exe start_proxy command.
Run the pwsync_admin.exe resume_plugin command.

Alternatively, if you wish to change only some Password Store settings (and not settings related to the plugin or the proxy) you may skip the reconfiguration command in the above steps.