PasswordSync

This chapter describes the Sun Java™ System Identity Manager PasswordSync feature, which enables Windows clients changing passwords in their Windows Active Directory and Windows NT domains to synchronize the changes with Identity Manager.

What is PasswordSync?

The PasswordSync feature keeps user password changes made on Windows Active Directory and Windows NT domains synchronized with other resources defined in Identity Manager. PasswordSync must be installed on each domain controller in the domains that will be synchronized with Identity Manager. PasswordSync must be installed separately from Identity Manager.

When PasswordSync has been installed on a domain controller, the controller communicates with a servlet that acts as a proxy for a Java Messaging Service (JMS) client. The servlet in turn communicates with a JMS-enabled message queue. A JMS Listener resource adapter removes messages from the queue and processes the password changes using a workflow task. The password is updated on all of the user’s assigned resources, and an SMTP server sends an email to the user, notifying the user of the status of the password change.

Before You Install PasswordSync

The PasswordSync feature can be set up only on Windows 2000, Windows 2003, and Windows NT domain controllers. You must install PasswordSync on each domain controller in the domains that will be synchronized with Identity Manager.

PasswordSync requires connectivity with a JMS server. See the documentation for the JMS Listener resource adapter in the Identity Manager Resources Reference for information about the requirements for the JMS system.

Microsoft .NET 1.1 or later must be installed on each domain controller

Any previous versions of PasswordSync must be removed

Install Microsoft .NET 1.1

To use PasswordSync, you must install the Microsoft .NET 1.1 (or later) Framework.
This Framework is installed by default if you are using a Windows 2003 domain controller. If you are using a Windows 2000 or Windows NT domain controller, you can download the toolkit from the Microsoft Download Center at:

Microsoft .NET 1.1 Framework requires Internet Explorer 5.01 or later.
Internet Explorer 5.0 (bundled with Windows 2000 SP4) is not sufficient.

Enter NET Framework 1.1 Redistributable in the Keywords search field to quickly locate the framework toolkit.

The toolkit installs the .NET 1.1 framework.

Uninstall Previous Versions of PasswordSync

You must remove any previously installed instances of PasswordSync before installing a later version.

If the previously installed version of PasswordSync supports the IdmPwSync.msi installer, you can use the standard Windows Add/Remove Programs utility to remove the program.

If the previously installed version of PasswordSync does not support the IdmPwSync.msi installer, use the InstallAnywhere uninstaller to remove the program.

Installing PasswordSync

This procedure describes how to install provides instructions for installing, configuring, and uninstalling the PasswordSync configuration application.

From the Identity Manager installation media, click on the pwsync\IdmPwSync.msi icon. The Welcome window is displayed

The installation wizard provides the following navigational buttons:

Cancel: Click to exit the wizard at any time without saving any of your changes.

Back: Click to return to a previous dialog box.

Next: Click to progress to the next dialog box.

Read the information provided on the Welcome screen, and then click Next to display the Choose Setup Type PasswordSync Configuration window.
PasswordSync Setup

Click either Typical or Complete to install the full PasswordSync package, or Custom to control which parts of the package are installed.

Click Install to install the product. The following window is displayed when PasswordSync has been installed successfully.

Click Finish to complete the installation process. Make sure Launch Configuration Application is selected so that you can begin configuring Password Sync. See Configuring PasswordSync for details about this process.

The following table identifies the files that are installed on each domain controller.


Installed Component	Description
%$INSTALL_DIR$%\configure.exe	The PasswordSync configuration program.
%$INSTALL_DIR$%\configure.exe.manifest	Data file for the configuration program.
%$INSTALL_DIR$%\DotNetWrapper.dll	DLL that handles .NET SOAP communication
%$INSTALL_DIR$%\passwordsyncmsgs.dll	DLL that handles PasswordSync messages.
%SYSTEMROOT%\SYSTEM32\lhpwic.dll	Password Notification DLL This DLL implements the Windows PasswordChangeNotify() function.

Configuring PasswordSync

If you run the configuration application from the installer, the application displays the configuration screens as a wizard. After you have completed the wizard, each subsequent time you run the PasswordSync configuration application, you can navigate between screens by selecting a tab.

Start the PasswordSync configuration application, if it is not already running. By default, the configuration application is installed at Program Files —> Sun Java System Identity Manager PasswordSync —> Configuration.

The following dialog appears.

Server Configuration Dialog

Figure 1. Server Configuration Dialog

Edit the fields as necessary.

Server must be replaced with the fully-qualified host name or IP address where application server where Identity Manager is installed.

Protocol indicates whether to make secure connections to Identity Manager. If HTTP is selected, the default port is 80. If HTTPS is selected, the default port is 443.

Path specifies the path to Identity Manager on the application server.

URL is generated by concatenating the other fields together. The value cannot be edited within the URL field.

Click Next to display the proxy server configuration page.

Proxy Server Dialog

Figure 2. Proxy Server Dialog

Edit the fields as necessary.

Click Enable if a proxy server is required.

Server must be replaced with the fully-qualified host name or IP address of the proxy server.

Port: Specify an available port number for the server.
(The default proxy port is 8080 and the default HTTPS port is 443.)

Click Next to display the JMS Settings dialog.

JMS Settings Dialog

Figure 3. JMS Settings Dialog

Edit the fields as necessary.

User specifies the JMS user name that places new messages on the queue.

Password and Confirm specify the password for the JMS user.

Connection Factory specifies the name of the JMS connection factory that should be used. This factory must already exist on the JMS system.

In most cases, Session Type should be set to LOCAL, which indicates that a local session transaction will be used. The session will be committed after each message is received. Other possible values include AUTO, CLIENT, and DUPS_OK.

Queue Name specifies the destination for the password synchronization events.

Click Next to display the JMS Properties dialog.

JMS Properties Dialog

Figure 4. JMS Properties Dialog

The JMS Properties dialog allows you to define the set of properties that are used to build the initial JNDI context. The following name/value pairs must be defined:

java.naming.provider.url — The value must be set to the URI of the machine running the JNDI service.

java.naming.factory.initial — The value must be set to the classname (including the package) of the Initial Context Factory for the JNDI Service Provider.

The Name pull-down menu contains a list of classes from the java.naming package. Select a class or type in a class name, then enter its corresponding value in the Value field.

Click Next to display the Email dialog.

The Email dialog enables you to configure whether to send an email notification when a user’s password change does not synchronize successfully due to a communication error or other error outside of Identity Manager.

Email Dialog

Figure 5. Email Dialog

Edit the fields as necessary.

Select Enable Email to enable this feature. Select Email End User if the user is to receive notifications. Otherwise, only the administrator will be notified.

SMTP Server is the fully qualified name or IP address of the SMTP server to be used when sending failure notifications.

Administrator Email Address is the email address used to send notifications.

Sender’s Name is the “friendly name” of the sender.

Sender’s Address is the email address of the sender.

Message Subject specifies the subject line of all notifications

Message Body specifies the text of the notification.

The message body may contain the following variables:

$(accountId) — The accountId of the user attempting to change password.

$(sourceEndpoint) — The host name of the domain controller where the password notifier is installed, to help locate troubled machines.

$(errorMessage) — The error message that describes the error that has occurred.

Click Finish to save your changes.

If you run the configuration application again, a set of tabs is displayed, instead of a wizard. If you want to display the application as a wizard, enter the following command from the command line:

Debugging PasswordSync

This section provides details about finding information needed to diagnose problems encountered with PasswordSync. about using the configuration tool to enable tracing. It also lists registry keys that might be needed to debug PasswordSync or enable features that cannot be implemented from the configuration tool

Error Logs

PasswordSync writes all failures to the Windows Event Viewer. The source name for error log entries is PasswordSync.

Trace Logs

When the configuration tool is run for the first time, the wizard does not include a panel for configuring tracing. However, the Trace tab is displayed all subsequent times the tool is launched.

The Trace Level field specifies the level of detail PasswordSync will provide when it writes to the trace log. A value of 0 indicates that tracing is turned off, while a value of 4 provides the most detail.

When the trace file exceeds the size specified in the Max File Size (MB) field, PasswordSync moves the file to the basename with .bk appended. For example, if your trace file is set to C:\logs\pwicsvc.log, and your trace level is set to 100 MB, when the trace file exceeds 100 MB, PasswordSync renames the file C:\logs\pwicsvc.log.bk, and writes the new data to a new C:\logs\pwicsvc.log file.

Registry Keys

The registry keys listed in the following table may be edited using the Windows Registry Editor. The keys are located in the HKEY_LOCAL_MACHINE\SOFTWARE\Waveset\Lighthouse\PasswordSync key. Other keys are present in this location, but they may be edited with the configuration tool.


Key Name	Type	Description
allowInvalidCerts	REG_DWORD	If set to 1, sets the following flags on the .NET client: SECURITY_FLAG_IGNORE_UNKNOWN_CA INTERNET_FLAG_IGNORE_CERT_CN_INVALID INTERNET_FLAG_IGNORE_CERT_DATE_INVALID As a result, the client will tolerate certificates that have expired or have an invalid CN or hostname. It only applies when SSL is being used. This setting is useful when debugging in test environments where most of the certificates are produced from invalid certificate authorities (CAs). The default is 0.
clientConnectionFlags	REG_DWORD	Optional connection flags that will be passed on to the .NET SOAP client. The default is 0.
clientSecurityFlags	REG_DWORD	Optional security flags that can be passed to the .NET SOAP client. The default is 0.
installdir	REG_SZ	The directory where the PasswordSync application was installed.
soapClientTimeout	REG_DWORD	Timeout, in milliseconds, for a SOAP client to communicate to the Identity Manager server before failure.

Uninstalling PasswordSync

To uninstall the PasswordSync application, go to the Windows Control Panel and select Add or Remove Programs. Then select Sun Java System Identity Manager PasswordSync and click Remove.

.Deploying PasswordSync

To deploy PasswordSync, you must perform the following actions in Identity Manager:

Configure a JMS Listener Adapter

Implement the Synchronize User Password Workflow

Set Up Notifications

Configuring a JMS Listener Adapter

Once messages are being placed on a queue indirectly by the domain controllers, a resource adapter must be configured to accept those messages. You must create a JMS Listener resource adapter and configure it to communicate to the queue. See Identity Manager Resources Reference for more information about setting up this adapter.

Destination Type — This value will typically be set to Queue. Topics are not usually relevant because there is one subscriber and potentially multiple publishers.

Initial context JNDI properties — This text box defines the set of properties that are used to build the initial JNDI context. The following name/value pairs must be defined:

java.naming.provider.url — The value must be set to the URI of the machine running the JNDI service.

java.naming.factory.initial — The value must be set to the classname (including the package) of the Initial Context Factory for the JNDI Service Provider.

It may be necessary to define additional properties. The list of properties and values should match those specified on the JMS settings page of the configuration application.

JNDI Name of Connection factory — The name of a connection factory, as defined on the JMS server.

User and Password — The account name and password of the administrator that requests new events from the queue.

Reliable Messaging Support — Select LOCAL (Local Transactions). The other options are not applicable for password synchronization.

Message Mapping — Enter java:com.waveset.adapter.jms.
PasswordSyncMessageMapper. This class transforms messages from the JMS server into a format that can be used by the Synchronize User Password workflow.

Implementing the Synchronize User Password Workflow

The default Synchronize User Password workflow takes each request that comes in from the JMS Listener adapter and checks out, then back in the ChangeUserPassword viewer. After the checkin has completed, the workflow iterates over all the resources accounts and selects all of the resources, except the source resource. Identity Manager notifies the user by email whether the password change was successful on all resources.

If you want to use the default implementation of the Synchronize User Password workflow, assign it as the process rule for the JMS Listener adapter instance. Process rules may be assigned in the Active Sync wizard for the adapter.

If you want to modify the default Synchronize User Password workflow, copy the $WSHOME/sample/wfpwsync.xml file and make your modifications. Then import the modified workflow into Identity Manager.

Some possible modifications that you might want to make to the default workflow include:

Which entities are notified when a password is changed.

What happens if an Identity Manager account cannot be found.

How resources are selected in the workflow.

Whether to allow password changes from Identity Manager

For detailed information about using workflows, see Identity Manager Workflows, Forms, and Views.

Setting Up Notifications

Identity Manager provides the Password Synchronization Notice and Password Synchronization Failure Notice email templates. These templates inform users whether an attempt to change passwords across multiple resources was successful.

Both templates should be updated to provide company-specific information about what users should do if they need further assistance. See Understanding Email Templates in the chapter titled Configuration for more information.

Frequently Asked Questions about PasswordSync

Can PasswordSync be used in conjunction with other Windows password filters that are used to enforce custom password policies?

Yes, you can use PasswordSync in conjunction with other _WINDOWS_ password filters. It must, however, be the last password filter listed in the Notification Package registry value.

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Lsa\Notification Packages (value of type REG_MULTI_SZ)

By default, the installer places the Identity Manager password intercept at the end of the list, but if you installed the custom password filter after the installation, you will be required to move lhpwic to the end of the Notification Packages list.

You can use PasswordSync in conjunction with other Identity Manager password policies. When policies are checked on the Identity Manager server side, all resource password policies must pass in order for the password synchronization to be pushed out to other resources. Consequently, you should make the Windows native password policy as restrictive as the most restrictive password policy defined in Identity Manager.

Can the PasswordSync servlet be installed on a different application server than Identity Manager?

Yes. The PasswordSync servlet requires the spml.jar and idmcommon.jar JAR files, in addition to any JAR files required by the JMS application.

Does the PasswordSync service send passwords over to the lh server in clear text?

Although we recommend running PasswordSync over SSL, all sensitive data is encrypted before being sent to the Identity Manager server.

Sometimes password changes result in com.waveset.exception.ItemNotLocked?

If you enable PasswordSync, a password change (even one initiated from the user interface), will result in a password change on the resource, which causes the resource to contact Identity Manager.

If you configure thepasswordSyncThreshold workflow variable correctly, Identity Manager examines the user object and decides that it has already handled the password change. However, if the user or the administrator makes another password change for the same user, at the same time, the user object could be locked.

Previous Contents Next
Sun Java System Identity Manager 2005Q4M3 Administration