Previous Contents Index Next
Sun ONE Identity Synchronization for Windows Installation and Configuration Guide

> ## Chapter 6
> Synchronizing Existing Users

> This 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:

> - "Linking Users"
> - "User Resynchronization"
> - "Starting and Stopping Synchronization"
> - "Starting and Stopping Services"

> 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

> Users Exist In | Post-installation Steps to Follow
> --- | ---
> Windows | Sun ONE Directory Server | Existing users should be synchronized | Existing users should NOT be synchronized
> No | No | None | None
> No | Yes | Run idsync resync -o Sun -c to create existing Directory Server users in Windows | None
> Yes | No | Run idsync resync -c to create existing Windows users in Directory Server | Run idsync resync -u to populate the connector’s local cache of user entries.
> Yes | Yes | Run idsync linkusers to link users between Windows and Directory Server. Then run idsync resync or idsync resync -o Sun to synchronize existing user values between the two directories. | Run idsync resync -u to populate the connector’s local cache of user entries.

> Dealing With Existing Users

> ##

> Linking Users

> Prior 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:

> - Usage
> - idsync linkusers Central Log
> - idsync linkusers Caveats

> 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

> Argument | Description
> --- | ---
> -h | Configuration Directory hostname
> -p | Configuration Directory port number
> -D | Directory Manager bind distinguished name
> -w | Directory Manager Bind password
> -s | This is the name of the root suffix to use for adding the index. (Required) A root suffix is a distinguished name such as dc=example,dc=com. A single synchronized user database is supported on each host even in a multi-database Directory Server deployment. Ensure that users to be synchronized are within one database.
> -q | Configuration password
> -f | XML filename for linkusers
> [-a <ldap-filter>] | Specify an LDAP filter to control the linking of individuals or groups.
> -n | Run in safe mode. This will only log what would have happened if the linkusers operation were run. This allows you to preview the effects of an linkusers operation.
> -Z | Specify that SSL be used to provide certificate-based client authentication.
> -P <cert db path> | Specify the path and filename of the client’s certificate database. This file may be the same as the certificate database for an SSL-enabled version of Directory Server. When using the command on the same host as the Directory Server you may use the server’s own certificate database, for example: -P <installDir>/alias/slapd-<serverId>-cert7.db If -Z is specified and -P is not, the <cert db path> defaults to <current working directory>/cert7.db. Note: If the certificate database file is not found in the specified directory, an *empty* database will be created in that directory. The database consists of three files: cert7.db, key3.db, and secmod.db.
> -m <secmod db path> | Specify the path to the security module database. For example: /var/Sun/MPS/slapd-<serverID>/secmod.db You need to specify this option only if the security module database is in a different directory from the certificate database itself.

> 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:

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

> 2. 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)

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

> 4. 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 Resynchronization

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

> Note | If there are existing Windows users, then the idsync resync command must be run before synchronization is started. If you do not want to synchronize existing users to Directory Server, then run it with the -u flag, which only updates the object cache and does not synchronize the Windows’ entries to Directory Server. If you have existing Windows users, and you do not run idsync resync, then changes to these users may or may not be propagated, and depending on flow settings, they might even be automatically created in Directory Server. idsync resync must be run even if idsync resync was already run.

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

> Option | Meaning
> --- | ---
> -h | Configuration directory hostname.
> -p | Configuration directory port number.
> -D | Directory Manager bind distinguished name.
> -w | Directory Manager Bind password
> -s | Suffix of the configuration directory.
> -o | Controls the source of the resync operation. For example, if Windows is specified, then the attribute values in the Sun ONE Directory Server entries are set to the corresponding attribute values in the Windows directory source entry. The Default is Windows. If you run the resync command without the -o flag set, then the resync operation will update user entries in the Sun ONE Directory Server.
> -q | Configuration password.
> -l | Synchronized user list selection. Specifies individual synchronized user lists to synchronize. Multiple can be specified by repeating this option (e.g. –l SUL1 –l SUL2). If none are specified then all synchronized user lists are synchronized.
> -c | Create Users. If a corresponding user is not found at the destination directory source, then the scripts automatically create the user entry. If this option is not supplied, then users are not created. This option should only be used with an empty directory or a directory with users that have already been linked using idsync linkusers.
> -u | Update object cache. This option only updates the local cache of user entries for a Windows directory source. This prevents pre-existing Windows users from being created in the Sun ONE Directory Server. If this option is used, Windows user entries are not synchronized with Sun ONE Directory Server user entries. This option is only valid when the resync source is Windows.
> -a | Specify an LDAP filter to control the synchronization of individuals or groups.
> -i | Resets passwords of resynchronized Directory Server users (resynching to Sun only). After a Directory Server user’s password has been reset, the program will invoke on-demand password synchronization the next time that user logs on. This option has two possible values: ALL_USERS: Resets the passwords of all resynchronized users. NEW_USERS: Resets the passwords of users created during resynchronization.
> -Z | Specify that SSL be used to provide certificate-based client authentication.
> -N | Specify the certificate name to use for certificate-based client authentication, for example: -N "Directory-Cert".
> -P <cert db path> | Specify the path and filename of the client’s certificate database. This file may be the same as the certificate database for an SSL-enabled version of Directory Server. When using the command on the same host as the Directory Server you may use the server’s own certificate database, for example: -P <installDir>/alias/slapd-<serverId>-cert7.db If -Z is specified and -P is not, the <cert db path> defaults to <current working directory>/cert7.db. Note: If the certificate database file is not found in the specified directory, an *empty* database will be created in that directory. The database consists of three files: cert7.db, key3.db, and secmod.db.
> -m <secmod db path> | Specify the path to the security module database. For example: /var/Sun/MPS/slapd-<serverID>/secmod.db You need to specify this option only if the security module database is in a different directory from the certificate database itself.

> #### Example Usages

> Some sample combination of command line options are shown. The standard –h, -p, -D, -w, -s options have been omitted for brevity.

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

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

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

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

> 5. The same as 1. but only display and log what would occur (no users are modified or created):

> idsync resync -n

> 6. Synchronize all Sun ONE Directory Server users in Windows that have a last name (sn) of Smith:

> idsync resync -o Sun -a "(sn=Smith)"

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

> This section explains how to start and stop a Identity Synchronization for Windows instance. To start or stop synchronization:

> 1. Access the console.
> 2. In the navigation tree, select the appropriate Identity Synchronization for Windows instance and press Open.

> Enter the configuration data password.

> 3. To stop synchronization service press the Tasks tab and then Stop.
> 4. To start synchronization service press the Tasks tab and then Start.

> ##

> Starting and Stopping Services

> On 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

> Note | Pause 30 seconds after stopping the Identity Synchronization for Windows daemon/service before starting it again because it might take several seconds for a connector to cleanly shut itself down.

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

> Previous Contents Index Next

> Copyright 2003 Sun Microsystems, Inc. All rights reserved.