Chapter 9 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.


Note	A password change must pass the native password policy for the change request to be forwarded to the Identity Manager server for synchronization. If the proposed password change does not meet the native password policy, the ADSI displays an error dialog, and no synchronization data is sent to Identity Manager.

Before You Install

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 JMS Listener resource adapter section in the Sun Java™ System Identity Manager Resources Reference for more information about the requirements for the JMS system.

Install Microsoft .NET 1.1 or later on each domain controller

Remove any previous versions of PasswordSync

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:

Uninstall Previous Versions of PasswordSync


Note	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.

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

The following procedure describes how to install the PasswordSync configuration application.


Note	You must install PasswordSync on each domain controller in the domains that will be synchronized with Identity Manager.

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.

A message displays to let you know if you installed PasswordSync successfully.

Click Finish to complete the installation process.

Be sure to select Launch Configuration Application so that you can begin configuring Password Sync. See Configuring PasswordSync for details about this process.



Note	A dialog stating that you must restart the system for the changes to take effect displays. It is not necessary to restart until after you have configured PasswordSync, but you must restart the domain controller before implementing PasswordSync.

Table 9-1 Domain Controller Files
Installed Component	Description
%$INSTALL_DIR$%\configure.exe	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 that 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 PasswordSync Configuration dialog is displayed (see Figure 9-1).

Figure 9-1 PasswordSync Configuration Dialog
The Server Configuration dialog

Edit the fields as necessary.

Server must be replaced with the fully-qualified host name or IP address 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 (Figure 9-2).

Figure 9-2 Proxy Server Dialog
The 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 (Figure 9-3).

Figure 9-3 JMS Settings Dialog
The 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 to 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 Lookup Name for the password synchronization events.

Click Next to display the JMS Properties dialog (Figure 9-4).

Figure 9-4 JMS Properties Dialog
The 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 URL 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 (Figure 9-5).

Figure 9-5 Email Dialog
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.

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 wish 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 (Figure 9-6)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

You can use the Windows Registry Editor to edit the registry keys listed in Table 9-2 . These keys are located in:

Other keys are present in this location, but they can be edited with the configuration tool.

Table 9-2 Registry Keys
Key Name	Type	Description
allowInvalidCerts	REG_DWORD	If set to 1, this key 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.


Note	PasswordSync can also be uninstalled (or reinstalled) by loading the Identity Manager installation media and clicking on the pwsync\IdmPwSync.msi icon.

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 Sun Java™ System 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.

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 of the modifications 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 Sun Java™ System 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 Customizing Email Templates.

Configuring PasswordSync with a Sun JMS Server

Identity Manager provides a JMS Listener adapter that enables password change events to be queued on a JMS message server for improved reliability and guaranteed delivery.

Using a sample scenario, this section provides instructions for configuring PasswordSync with a Sun JMS server. The information is organized as follows:


Note	See the Sun Java™ System Identity Manager Resources Reference for more information about this adapter.

Overview

Creating and Storing Administered Objects

Debugging Your Configuration

Overview

This section describes the sample scenario, the Windows PasswordSync solution, and the JMS solution.

Sample Scenario

A typical (simple) use case for configuring PasswordSync with a JMS server is to enable users to change their passwords on Windows, have Identity Manager pick up the new password, and then update the user accounts with the new passwords on a Sun Directory Server.

Windows Server 2003 Enterprise Edition – Active Directory

Sun Java™ System Identity Manager 6.0 2005Q4M3

MySQL 4.1.13 running on Suse Linux 10.0

Tomcat 5.0.28 running on Suse Linux 10.0

Sun Java™ System Message Queue 3.6 SP3 2005Q4 running on Suse Linux 10.0

Sun Java™ System Directory Server 5.2 SP4 running on Suse Linux 10.0

Java 1.4.2

The following files were copied to the Tomcat common/lib directory to enable JMS and JNDI:

jms.jar (from Sun Message Queue)

fscontext.jar (from Sun Message Queue)

imq.jar (from Sun Message Queue)

jndi.jar (from Java JDK)

Solution Overview

When you analyze all the components that act in the Windows PasswordSync solution, here is what takes place:

When users change their passwords on their workstations, PasswordSync sends a password modification to the current Active Directory domain controller and the Identity Manager password capture dll (residing on the domain controller) captures the clear text password.

The password capture dll initiates a SOAP request to the Identity Manager SOAP request handler.

The user ID, the encrypted password, and the necessary JMS configuration information are encapsulated in this SOAP request. For example,

Code Example 9-1 Example SOAP Request


POST /idm/servlet/rpcrouter2 HTTP/1.0
Accept: text/*
SOAPAction: "urn:lighthouse"
Content-Type: text/xml; charset=utf-8
User-Agent: VCSoapClient
Host: 192.168.1.4:8080
Content-Length: 1154
Connection: Keep-Alive
Pragma: no-cache
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
<soap:Body soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<snp:queuePasswordUpdate xmlns:snp="urn:lighthouse">
<userEmailAddress xsi:nil="1"/>
<resourceAccountId>CN=John Smith,OU=people,DC=org,DC=local</resourceAccountId> <resourceAccountGUID>b4e1c14b79d3a949a618a607dde7784d</resourceAccountGUID>
<password>zkpS8qcIJkVBWa/Frp+JqA==</password>
<accounts xsi:nil="1"/>
<resourcename xsi:nil="1"/>
<resourcetype>Windows Active Directory</resourcetype>
<clientEndpoint>W2003EE</clientEndpoint>
<jmsUser>guest</jmsUser>
<jmsPassword>guest</jmsPassword>
<queueName>cn=pwsyncDestination</queueName>
<connectionFactory>cn=pwsyncFactory</connectionFactory>
<sessionType>LOCAL</sessionType>
<JNDIProperties>java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory;java.naming. provider.url=ldap://gwenig.coopsrccom:389/ou=sunmq,dc=coopsrc,dc=com</JNDIProperties>
<singleResult>true</singleResult>
</snp:queuePasswordUpdate>
</soap:Body>
</soap:Envelope>

The SOAP handler receives the request and uses the JMS parameters contained in the request to initiate a connection to the JMS Message Queue Broker. The SOAP handler then sends a message containing the user ID and the encrypted password (along with some other parameters to be discussed later).

For example, the SOAP handler on the Message Queue Broker sends a message (of type MapMessage) similar to the following:

Code Example 9-2 SOAP Handler Message


password: zkpS8qcIJkVBWa/Frp+JqA==
accounts: null
resourceAccountGUID: 8f245d1490de7a4192a8821c569c9ac4
requestTimestamp: 1143639284325
queueName: cn=pwsyncDestination
jmsUser: guest
resourcetype: Windows Active Directory
resourcename: null
JNDIProperties:
java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory;
java.naming.provider.url=ldap://gwenig.coopsrc.com:389/
ou=sunmq,dc=coopsrc,dc=com
connectionFactory: cn=pwsyncFactory
clientEndpoint: W2003EE
userEmailAddress: null
sessionType: LOCAL
jmsPassword: guest
resourceAccountId: CN=John Smith,OU=people,DC=org,DC=local

The Message Queue Broker queues the message and the JMS Listener adapter retrieves the message. Identity Manager can now initiate a workflow.

Figure 9-7 illustrates the configuration used in this sample scenario:



Note	Although this figure shows the SOAP handler and Identity Manager on separate server, you can run them both on the same server.

Figure 9-7 Scenario Configuration
Sample scenario configuration

JMS Overview

The Java Message Service (JMS) API is a messaging standard that allows application components (based on the Java 2 Platform, Enterprise Edition (J2EE)) to create, send, receive, and read messages. This API enables distributed communication that is loosely coupled, reliable, and asynchronous.

To send or receive messages, a JMS client must first connect to a JMS provider, which is often implemented as a message broker. This connection opens a channel of communication between the client and the broker. Next, the client must set up a session for creating, producing, and consuming messages.

Connection factories — Connection factory administered objects generate client connections to the broker. These objects encapsulate provider-specific information that governs certain aspects of messaging behavior; such as connection handling, client identification, message header overrides, reliability, and flow control, and so forth. Every connection derived from a given connection factory exhibits the behavior configured for that factory.

Destinations — Destination administered objects reference physical destinations on the broker. These objects encapsulate provider-specific naming (address-syntax) conventions and they specify the messaging domain within which the destination is used — queue or topic.

These two objects, rather than being created programmatically, are normally created and configured using administration tools. They are then stored in an object store, and accessed by a JMS client through standard JNDI lookups.


Note	For more information about connection factories and destinations, refer to the Sun Java™ System Message Queue Technical Overview located at: http://docs.sun.com/source/819-2574/intro.html

When the SOAP handler receives a request from the Windows password capture dll, the SOAP handler acts as a proxy to translate the SOAP request into a JMS message. The JMS Listener adapter then receives the message and triggers the relevant workflow.

To work with the JMS Broker, the Identity Manager SOAP handler and the Identity Manager JMS Listener adapter must both have a connection factory and a destination (looked up using JNDI).

The Identity Manager SOAP handler gets the necessary details in the SOAP message (as shown previously):

All of the following parameters (shown in the Figure 9-9 and Figure 9-10) are provided when you install and configure PasswordSync on Windows:

JMS Settings Parameters

JMS Properties Parameters

JMS Settings Parameters

User and Password fields: Define the credentials to use when connecting to the JMS broker.

Connection Factory field: Specify a JNDI lookup name for the connection factory object.

Session Type field: Specify

Queue Name field: Specify a JNDI lookup name for the destination object.

In Code Example 9-4, Connection Factory and Queue Name are LDAP RDNs, which (when coupled with the java.naming.provider.url) makes a full DN. A simple ldapsearch shows the administered object entry:

Code Example 9-4 Connection Factory and Queue Name Example


Connection Factory:
#> ldapsearch -h gwenig.coopsrc.com -b 'dc=coopsrc,dc=com' 'cn=pwsyncfactory'
dn: cn=pwsyncFactory,ou=sunmq,dc=coopsrc,dc=com
objectClass: top
objectClass: javaContainer
objectClass: javaObject
objectClass: javaNamingReference
javaClassName: com.sun.messaging.QueueConnectionFactory
javaFactory: com.sun.messaging.naming.AdministeredObjectFactory
javaReferenceAddress: #0#version#3.0
javaReferenceAddress: #1#readOnly#false
javaReferenceAddress: #2#imqOverrideJMSPriority#false
javaReferenceAddress: #3#imqConsumerFlowLimit#1000
javaReferenceAddress: #4#imqAddressListIterations#1
javaReferenceAddress: #5#imqOverrideJMSExpiration#false
javaReferenceAddress: #6#imqConnectionType#TCP
javaReferenceAddress: #7#imqLoadMaxToServerSession#true
javaReferenceAddress: #8#imqPingInterval#30
javaReferenceAddress: #9#imqSetJMSXUserID#false
javaReferenceAddress: #10#imqConfiguredClientID#
javaReferenceAddress: #11#imqSSLProviderClassname#com.sun.net.ssl.internal.ssl.Provider
javaReferenceAddress: #12#imqJMSDeliveryMode#PERSISTENT
javaReferenceAddress: #13#imqConnectionFlowLimit#1000
javaReferenceAddress: #14#imqConnectionURL#http://localhost/imq/tunnel
javaReferenceAddress: #15#imqBrokerServiceName#
javaReferenceAddress: #16#imqJMSPriority#4
javaReferenceAddress: #17#imqBrokerHostName#localhost
javaReferenceAddress: #18#imqJMSExpiration#0
javaReferenceAddress: #19#imqAckOnProduce#
javaReferenceAddress: #20#imqEnableSharedClientID#false
javaReferenceAddress: #21#imqAckTimeout#0
javaReferenceAddress: #22#imqAckOnAcknowledge#
javaReferenceAddress: #23#imqConsumerFlowThreshold#50
javaReferenceAddress: #24#imqDefaultPassword#guest
javaReferenceAddress: #25#imqQueueBrowserMaxMessagesPerRetrieve#1000
javaReferenceAddress: #26#imqDefaultUsername#guest
javaReferenceAddress: #27#imqReconnectEnabled#false
javaReferenceAddress: #28#imqConnectionFlowCount#100
javaReferenceAddress: #29#imqAddressListBehavior#PRIORITY
javaReferenceAddress: #30#imqReconnectAttempts#0
javaReferenceAddress: #31#imqSetJMSXAppID#false javaReferenceAddress:
#32#imqConnectionHandler#com.sun.messaging.jmq.jmsclient.protocol.
tcp.TCPStreamHandler
javaReferenceAddress: #33#imqSetJMSXRcvTimestamp#false
javaReferenceAddress: #34#imqBrokerServicePort#0
javaReferenceAddress: #35#imqDisableSetClientID#false
javaReferenceAddress: #36#imqSetJMSXConsumerTXID#false
javaReferenceAddress: #37#imqOverrideJMSDeliveryMode#false
javaReferenceAddress: #38#imqBrokerHostPort#7676
javaReferenceAddress: #39#imqQueueBrowserRetrieveTimeout#60000
javaReferenceAddress: #40#imqSSLIsHostTrusted#true
javaReferenceAddress: #41#imqSetJMSXProducerTXID#false
javaReferenceAddress: #42#imqConnectionFlowLimitEnabled#false
javaReferenceAddress: #43#imqReconnectInterval#3000
javaReferenceAddress: #44#imqAddressList#mq://gwenig:7676/jms
javaReferenceAddress: #45#imqOverrideJMSHeadersToTemporaryDestinations#false
cn: pwsyncFactory

Code Example 9-5 Destination Example


#> ldapsearch -h gwenig.coopsrc.com -b 'dc=coopsrc,dc=com' 'cn=pwsyncdestination'
dn: cn=pwsyncDestination,ou=sunmq,dc=coopsrc,dc=com
objectClass: top
objectClass: javaContainer
objectClass: javaObject
objectClass: javaNamingReference
javaClassName: com.sun.messaging.Queue
javaFactory: com.sun.messaging.naming.AdministeredObjectFactory
javaReferenceAddress: #0#version#3.0
javaReferenceAddress: #1#readOnly#false
javaReferenceAddress: #2#imqDestinationName#pwsyncQueue
javaReferenceAddress: #3#imqDestinationDescription#A Description for the Destination Object
cn: pwsyncDestination

JMS Properties Parameters

In the sample scenario, the connection factory and the destination objects reside in an LDAP directory. The java.naming.factory.initial is the factory class value used to create an initial JNDI context. The java.naming.provider.url holds the name of the environment property used to specify configuration information for the service provider being used. If you do not provide more information, PasswordSync uses an anonymous LDAP session to retrieve the connection factory and destination objects.

java.naming.security.principal: Bind DN (for example, cn=Directory manager)

java.naming.security.authentication: Bind method (for example, simple)

java.naming.security.credentials: Password



Note	You must define these same settings for the JMS Listener adapter.

Figure 9-11 JMS Listener Resource Parameters Page

Both the SOAP Handler and the JMS Listener adapter must search for the connection factory and the destination in order to send/receive messages.

Creating and Storing Administered Objects

This section provides instructions for creating and storing the following administered objects, which are required for the sample scenario to work successfully:

Connection factory objects

Destination objects



Note	The instructions in this section assume you have installed Sun Java™ System Message Queue. (The necessary tools are located in the bin/ directory of your Message Queue installation.) You can use either the Message Queue administrative GUI (imqadmin) or the command-line tool (imqobjmgr) to create these administered objects. The following instructions use the command-line tool.

Storing Administered Objects in an LDAP Directory

This section provides the commands you need to store connection factory objects in an LDAP directory.

Storing Connection Factory Objects

Code Example 9-6 Storing Connection Factory Objects


#> ./imqobjmgr add -l "cn=mytestFactory"
-j "java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory"
-j "java.naming.provider.url=ldap://gwenig.coopsrc.com:389/ou=sunmq,dc=coopsrc,dc=com"
-j "java.naming.security.principal=cn=directory manager"
-j "java.naming.security.credentials=password"
-j "java.naming.security.authentication=simple"
-t qf
-o "imqAddressList=mq://gwenig.coopsrc.com:7676/jms"
Adding a Queue Connection Factory object with the following attributes:
imqAckOnAcknowledge [Message Service Acknowledgement of Client Acknowledgements]
...
imqSetJMSXUserID [Enable JMSXUserID Message Property] false

Using the following lookup name:
cn=mytestFactory
The object's read-only state: false
To the object store specified by:
java.naming.factory.initial com.sun.jndi.ldap.LdapCtxFactory
java.naming.provider.url ldap://gwenig.coopsrc.com:389/ou=sunmq,dc=coopsrc,dc=com
java.naming.security.authentication simple
java.naming.security.credentials netscape
java.naming.security.principal cn=directory manager
Object successfully added.

Where imqAddressList defines the JMS server/broker hostname (gwenig.coopsrc.com), port (7676) and the access method (jms).

Storing Destination Objects

Code Example 9-7 Storing Destination Objects


#> ./imqobjmgr add -l "cn=mytestDestination"
-j "java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory"
-j "java.naming.provider.url=ldap://gwenig.coopsrc.com:389/ou=sunmq,dc=coopsrc,dc=com"
-j "java.naming.security.principal=cn=directory manager"
-j "java.naming.security.credentials=password"
-j "java.naming.security.authentication=simple"
-t q
-o "imqDestinationName=mytestDestination"
Adding a Queue object with the following attributes:
imqDestinationDescription [Destination Description] A Description for the Destination Object imqDestinationName [Destination Name] mytestDestination
Using the following lookup name:
cn=mytestDestination
The object's read-only state: false
To the object store specified by:
java.naming.factory.initial com.sun.jndi.ldap.LdapCtxFactory
java.naming.provider.url ldap://gwenig.coopsrc.com:389/
ou=sunmq,dc=coopsrc,dc=com
java.naming.security.authentication simple
java.naming.security.credentials netscape java.naming.security.principal cn=directory manager
Object successfully added.

Storing Administered Objects in a File

This section explains how to use the command line tool to store administered objects in a file.

Storing Connection Factory Objects


Note	You can check the newly created object with an ldapsearch or an ldap browser.

Code Example 9-8 provides the commands you need to store connection factory objects and specify a lookup name:

Code Example 9-8 Storing Connection Factory Objects and Specifying Lookup Names


#> ./imqobjmgr add -l "mytestFactory" -j "java.naming.factory.initial= com.sun.jndi.fscontext.RefFSContextFactory"
-j "java.naming.provider.url=file:///home/gael/tmp" -t qf -o "imqAddressList=mq://gwenig.coopsrc.com:7676/jms"
Adding a Queue Connection Factory object with the following attributes:
imqAckOnAcknowledge [Message Service Acknowledgement of Client Acknowledgements]
...
imqSetJMSXUserID [Enable JMSXUserID Message Property] false
Using the following lookup name:
mytestFactory
The object's read-only state: false To the object store specified by:
java.naming.factory.initial com.sun.jndi.fscontext.RefFSContextFactory java.naming.provider.url file:///home/gael/tmp
Object successfully added.
To specify a destination:
#> ./imqobjmgr add -l "mytestQueue" -j "java.naming.factory.initial=com.sun.jndi.fscontext.RefFSContextFactory"
-j "java.naming.provider.url=file:///home/gael/tmp" -t q -o "imqDestinationName=myTestQueue"
Adding a Queue object with the following attributes:
imqDestinationDescription [Destination Description] A Description for the Destination Object imqDestinationName [Destination Name] myTestQueue
Using the following lookup name:
mytestQueue
The object's read-only state: false
To the object store specified by:
java.naming.factory.initial com.sun.jndi.fscontext.RefFSContextFactory java.naming.provider.url file:///home/gael/tmp
Object successfully added.

Creating the Destination on the Broker

By default, the Sun Java System Message Queue broker allows auto-creation of the queue destination (see config.properties, where the default value for imq.autocreate.queue is true).

If the queue destination is not created automatically, you must create the destination object on the broker using the command shown in Code Example 9-9 (where myTestQueue is the destination):

In a directory: If the Identity Manager SOAP handler and the Identity Manager server are not running on the same server in your Identity Manager deployment, using a directory is a centralized way of storing the Connection Factory and the Destination objects.


Note	If the Identity Manager SOAP handler and the Identity Manager server are not on the same machine, then each of them must be able to access the .bindings file. You can repeat the administered object creation twice (on each machine) or you can copy the .bindings file to the proper location on each machine.

In a file: If the Identity Manager SOAP handler and Identity Manager server are both running on the same server (or if you do not have a directory available), you can store the administrative objects in a file.

Configuring the JMS Listener Adapter for this Scenario

The first page of the JMS Listener adapter configuration should look similar to one in Figure 9-13:

Specify java:com.waveset.adapter.jms.PasswordSyncMessageMapper in the Message Mapping field to transform incoming JMS messages to a format that can be used by the Synchronize User Password workflow.

For this scenario, map the following attributes (which are made available to the JMS Listener Adapter by PasswordSyncMessageMapper):

IDMAccountId: This attribute is resolved by the PasswordSyncMessageMapper, based on the resourceAccountId and resourceAccountGUID attributes passed in the JMS message.

password: The encrypted password is received in the SOAP request and forwarded in the JMS message.

Figure 9-14 Mapping IDMAccountId and password Account Attributes

When you configure these attribute fields in the schema map, the attributes become available to the resource in the Attribute Mappings section of the Active Sync Wizard (Figure 9-15).



Note	No identity template is provided here.

Figure 9-15 Active Sync Attribute Mappings

Configuring Active Sync

Use the Active Sync wizard for the JMS Listener with the advanced configuration mode to configure Active Sync for this scenario.

When the Synchronization Mode screen displays (Figure 9-16), you can leave the parameters set to their default values, and click Next to continue.

The default Synchronize User Password workflow takes each request that comes in from the JMS Listener adapter, checks out the ChangeUserPassword viewer, and then checks the ChangeUserPassword viewer back in.

Figure 9-16 Synchronization Mode Screen

When the Active Sync Running Settings panel displays, you must define a Proxy administrator (pwsyncadmin) that is associated with an empty form.

Figure 9-17 Active Sync Running Settings Panel

For debugging purposes, set the Log Level to 4 and specify a Log File Path to generate a verbose log file in a particular directory.

For example, the log file shown in Figure 9-17 will be saved to the /dvlpt/Idm/pwsynctests/logs/ directory.

When you are finished, click Next to continue.

Do not change the default values in the next two Active Sync wizard panels. Simply click Next until the Target Resources screen displays (Figure 9-18).

Figure 9-18 Target Resources Screen
Target Resources page

Use the Target Resources selection tool to specify the target resources. Select resources from the Available Resources list and click the

button to move the resources into the Target Resources list.

For example, in this scenario you want to synchronize the Windows password with a Sun Directory Server and you want to synchronize the Identity Manager password.

Click Next, and when the Target Attribute Mappings panel displays, select the IDM User tab (if not already selected).

On the IDM User tab, use the table to specify target attribute mappings for the Identity Manager User.

For example, password and accountID are defined in Figure 9-19:

Figure 9-19 Defining password and accountID
Mapping password and accountID target attributes

When you are finished, click Add Mapping.

Select the LDAP-kosig tab to define the target attribute mappings for the Sun Directory (Figure 9-20):

Figure 9-20 Defining Target Attribute Mappings for Sun Directory

When you are finished, click Add Mapping, and then save your changes.

Debugging Your Configuration

You can use the Windows PasswordSync Configuration application to debug the Windows side of your configuration.

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.

When the PasswordSync Configuration dialog displays, click the Test button.

The Test Connection dialog (Figure 9-21) displays, with a message stating whether the test connection completed successfully.

Figure 9-21 Test Connection Dialog

Click Close to close the Test Connection dialog.

Click OK to close the PasswordSync Configuration dialog.

The JMS Listener adapter then runs in debug mode, and generates debug information in a file, similar to the one in Figure 9-22:

Figure 9-22 Debug Information File
Debugging information

Failover Deployment for PasswordSync

PasswordSync’s architecture provides for the elimination of any single point of failure in the Windows password synchronization deployment for Identity Manager.

If you configure each Active Directory Domain Controller (ADC) to connect to one in a series of JMS clients through a Load Balancer (see Figure 9-23), the JMS clients can send messages to a Message Queue Broker cluster, which ensures that no messages will be lost if any Message Queue fails.

The Identity Manager server that is running the JMS Listener adapter configured for automatic failover will contact the Message Queue broker cluster. Although the adapter executes on only one Identity Manager at a time, if the primary ActiveSync server fails, the adapter will begin polling for password-related messages on a secondary Identity Manager server and propagating password changes out to downstream resources.


Note	Your Message Queue cluster probably requires a database for persistence of messages. (Instructions for configuring a Message Queue broker cluster should be provided in your vendor’s product documentation.)

Frequently Asked Questions about PasswordSync

Can PasswordSync be implemented without a Java Messaging Service?

Yes, but doing so eliminates the advantages of using a JMS to track password change events.

To implement PasswordSync without a JMS, launch the configuration application with the following flag:

When the -direct flag is specified, the configuration application displays the User tab. Configure PasswordSync using the procedures described in Configuring PasswordSync, with the following exceptions:

Do not configure the JMS Settings and JMS Properties tabs.

In the User tab, specify the account ID and password that will be used to connect to Identity Manager.

If you implement PasswordSync without a JMS, you do not need to create a JMS Listener adapter. Therefore, you should omit the procedures listed in Deploying PasswordSync. If you want to set up notifications, you may need to alter the Change User Password workflow.

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)


Note	If you subsequently run the configuration application without specifying the -direct flag, PasswordSync will require a JMS to be configured. Relaunch the application with the -direct flag to bypass the JMS again.

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?


Note	The password intercept DLL does not enforce any password policies.

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 the passwordSyncThreshold 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 Index Next
Sun Java[TM] System Identity Manager 7.1 Admininstration