| Sun ONE Identity Synchronization for Windows Installation and Configuration Guide |
Chapter 6
Synchronizing Existing UsersThis chapter contains information for linking and resynchronizing existing users for new Identity Synchronization for Windows installations. Users should be linked after core and connector installation has been completed.
This chapter includes the following sections:
Identity Synchronization for Windows provides two command line utilities that bootstrap deployments with existing users:
idsync linkusers. This command uses administrator-specified matching rules to pair up existing entries
idsync resync. This command can populate an empty directory with the contents of a remote directory or bulk synchronize attribute values between two existing user populations.
This table summarizes the post-installation steps to follow based on existing user populations:
Table 6-1
Dealing With Existing Users
Linking UsersPrior to starting synchronization for your network ensure that all existing users are linked between directory sources. The idsync linkusers command enables administrators to link existing users in two directory sources. Run this command after all connectors have been installed. The directory administrator provides rules for matching users between the two directories (for example: for a user entry to be linked in the two directories both the first names and last names must match in both directory entries).
Note
When there are existing users, you must run the idsync resync command after running idsync linkusers. If you do not resynchronize existing users, the resynchronization behavior remains undefined.
For more information about the idsync resync command, see "User Resynchronization".
This section describes how to run this command in the following sections:
Once Active Directory and Directory Server have been populated with users and the Active Directory and Directory Server connectors have been installed (but synchronization has not been started), the idsync linkusers command can be used to link the existing users.
Usage
The idsync linkusers command accepts the following arguments:
Table 6-2 idsync linkusers Usage
To link the existing users using the sample IlodeLinkUsersIntegrate.cfg file (see LinkUsers XML Document Sample for a listing of this file),
Linking user entries and resolving data conflicts could be described as more art than science. There are many reasons why the idsync linkusers command might fail to link two users in opposing directory sources and depends to a large extent on the consistency of the data in the linked directories.
One strategy for using idsync linkusers is to use the “safe mode” flag to refine the linking criteria gradually until an optimum set of user matching criteria is found (see Appendix B) for a reference in defining matching criteria). You should realize however that there is a balance to be achieved through linkage accuracy and linkage coverage. For instance, if both directory sources contain an employee ID or social security number, you should probably begin with linking criteria that includes this number only. You might feel that in order to improve linkage accuracy, you might include a last name attribute in the criteria as well. However, you may then lose linkages for entries that would have matched on ID alone due to inconsistent last name values in the data. These objects will have to be manually linked. To do manual linking of entries could be done in any number of ways involving your favorite LDAP tools including browsers and command-line tools.
In the following example, if you have specified a user matching criteria specifying linkages to be established between user object having the same value for the sn and givenname attributes. Proceed as follows:
- run idsync linkusers as follows:
root@example:/var/sun/mps/isw-hostname/bin $ idsync linkusers -h hostname -p 389 -D "cn=Directory Manager" -w dirmanager -s dc=example,dc=com -q password -f ../samples/ILodeLinkUsersIntegrate
User linking operation started. Enter ’c’ to cancel.
Progress: Dumped=7, Previously linked=0, Successfully linked=2,
Failed to link=4
Success- View the linking log file at under the logs directory:
[2002/12/11 21:47:01.267 -0600] INFO 14 CNN101 davide "Destination - Matched Remote Entry=’[sn=Smith, employeenumber=1000, givenname=Alice] [uid=AliceSmith]’to Local Entry=’[Action operation =9, Action DN = CN=Alice Smith,OU=people,DC=central,DC=example,DC=com, attrname = givenname, attrValue = Alice(hex value: 416C696365), op type = 0, attrname = sn, attrValue = Smith(hex value: 536D697468), op type = 0, attrname = uid, attrValue = AliceSmith(hex value: 416C696365536D697468), op type = 0, Attribute name = nsuniqueid, Attribute value = c2c0a184-1dd111b2-80a5faf5-9800ff15(hex value: 63326330613138342D31646431313162322D38306135666166352D3938303066 663135)
[2002/12/11 21:47:01.708 -0600] INFO 14 CNN101 davide "Destination Failed to Link Entry=’[sn=Hayes, employeenumber=1002, givenname=Charlie] [uid=Charlie Hayes]’" (Action ID=6, SN=6)
[2002/12/11 21:48:28.182 -0600] INFO 21 CNN101 davide "Destination - Entry=’[sn=Smith, employeenumber=1000, givenname=Alice] [uid=AliceSmith]’ already linked." (Action ID=13, SN=4)
- Notice in the above example that Charlie Hayes entry did not match. The first thing to suspect in such a case would be data consistency. You might try locating the user entry in the directory using ldapsearch and searching for entries where sn=Hayes:
root@example:/var/sun/mps/isw-hostname/bin $ ldapsearch -D "cn=directory manager" -w dirmanager -h hostname -b dc=central,dc=example,dc=com sn=Hayes
uid=CHayes,ou=People, dc=central,dc=example,dc=com
uid=CHayes
objectClass=top
objectClass=person
objectClass=organizationalPerson
objectClass=inetorgperson
sn=Hayes
cn=Charles Hayes
givenName=Charles- This search reveals the linking problem to be one of data inconsistency. The simplest way to resolve this problem would be to change the givenname attribute value from Charles to Charlie or visa versa on the opposite directory source. Continue trying to resolving data inconsistencies for all match failures or refine the user match criteria and rerun idsync linkusers until you have achieved an acceptable percentage of entry linkages.
idsync linkusers Central Log
The result of all idsync linkusers operations are reported in a special central log named linking.log. This log lists all of the users that were properly linked, those that failed to link, and those that were previously linked. An example of each is shown below. The “already linked” case was generated by rerunning the same idsync linkusers operation.
[2002/12/11 21:47:01.267 -0600] INFO 14 CNN101 davide "Destination - Matched Remote Entry='[sn=Smith, employeenumber=1000, givenname=Alice] [uid=AliceSmith]' to Local Entry='[Action operation =9, Action DN = CN=Alice Smith,OU=people,DC=central,DC=sun,DC=com, attrname = givenname, attrValue = Alice(hex value: 416C696365), op type = 0, attrname = sn, attrValue = Smith(hex value: 536D697468), op type = 0, attrname = uid, attrValue = AliceSmith(hex value: 416C696365536D697468), op type = 0, Attribute name = nsuniqueid, Attribute value = c2c0a184-1dd111b2-80a5faf5-9800ff15(hex value: 63326330613138342D31646431313162322D38306135666166352D3938303066663135)
[2002/12/11 21:47:01.708 -0600] INFO 14 CNN101 davide "Destination Failed to Link Entry='[sn=Hayes, employeenumber=1002, givenname=Charlie] [uid=Charlie Hayes]'" (Action ID=6, SN=6)
[2002/12/11 21:48:28.182 -0600] INFO 21 CNN101 davide "Destination - Entry='[sn=Smith, employeenumber=1000, givenname=Alice] [uid=AliceSmith]' already linked." (Action ID=13, SN=4)
Note some pre-existing special Active Directory users such as Administrator and Guest might appear in this log as failures.
idsync linkusers Caveats
Beware of the following when running idsync linkusers:
Indexed Attributes
Attributes used in an idsync linkusers operation should be indexed. If there are multiple attributes in a UserMatchingCriteria and at least one of them is indexed, then performance will probably be acceptable. If no attributes in a UserMatchingCriteria are indexed, then performance will be unacceptable with a large directory.
Undefined Synchronization Behavior
After running idsync linkusers, you must resynchronize existing users (run idsync resync) or the resynchronization behavior will remain undefined.
User ResynchronizationPrior to starting synchronization for your network ensure that all existing users are synchronized between servers. User Resynchronization idsync resync enables an administrator to bulk resynchronize two directory sources. Idsync resync can create users and synchronize attributes, but it cannot synchronize passwords. (The one exception to password synchronization is invalidating the Sun ONE Directory Server password to force on-demand password synchronization in an Active Directory environment.)
- idsync resync can populate an empty Sun ONE Directory Server with existing Active Directory or NT domain users.
- After running idsync linkusers to link users in two existing directory sources, idsync resync can synchronize all user entry attribute values (other than passwords) in the two directories.
- If two directory sources become out of sync, then idsync resync can synchronize user entries.
- Idsync resync can “prime” the object cache database of the NT and Active Directory connectors. The object cache maintains a shadow copy of the Active Directory or NT SAM user entires.
Usage
The idsync resync command accepts the following arguments:
Table 6-3 idsync resync Usage
Example Usages
Some sample combination of command line options are shown. The standard –h, -p, -D, -w, -s options have been omitted for brevity.
- Update the value of all Sun ONE Directory Server user attribute values with the values of the attributes in the Windows environment, but do not create users that cannot be found:
idsync resync
- The same as 1. except the passwords of all users are invalidated to force on-demand synchronization. This command is only valid in an AD only environment. In a mixed environment with both AD and NT domains, the AD SULs must be listed explicitly
idsync resync -i ALL_USERS
- The same as 1. except users that are not found are created in Sun ONE Directory Server and their passwords are invalidated to force on-demand synchronization. This command can be used to populate an empty Sun ONE Directory Server instance with existing Windows users.
idsync resync -c -i NEW_USERS
- Create all existing AD users in Sun ONE Directory Server for only the SUL_sales and SUL_finance SULs (but do not force on-demand synchronization)
idsync resync -c SUL_sales SUL_finance
- The same as 1. but only display and log what would occur (no users are modified or created):
idsync resync -n
- Synchronize all Sun ONE Directory Server users in Windows that have a last name (sn) of Smith:
idsync resync -o Sun -a "(sn=Smith)"
- Only update the object cache for Windows connectors to prevent existing user from being created in Directory Server. No users are actually synchronized:
idsync resync -u
Logging
Events from a idsync resync operation are logged to the same logs as linkusers operations. They are logged to the linking.log file.
Starting and Stopping SynchronizationThis section explains how to start and stop a Identity Synchronization for Windows instance. To start or stop synchronization:
- Access the console.
- In the navigation tree, select the appropriate Identity Synchronization for Windows instance and press Open.
Enter the configuration data password.
- To stop synchronization service press the Tasks tab and then Stop.
- To start synchronization service press the Tasks tab and then Start.
Starting and Stopping ServicesOn Solaris, Identity Synchronization for Windows and the Sun ONE Message Queue are installed as daemons. They are started automatically when the system boots. The /etc/init.d/isw and /etc/init.d/imq scripts can be used to start and stop these daemons manually. For example,
- /etc/init.d/isw start starts all Identity Synchronization for Windows processes
- /etc/init.d/isw stop stops all Identity Synchronization for Windows processes
- /etc/init.d/imq start starts the Message Queue broker
- /etc/init.d/imq stop stops the Message Queue broker
On Windows, Identity Synchronization for Windows and the Sun ONE Message Queue are installed as Windows services. The “Sun ONE Identity Synchronization for Windows“and “iMQ. Broker” services are started up automatically when the system boots. To control them manually, use the Services control panel or the net command.
