Sun Java System Directory Server Enterprise Edition 6.2 Installation Guide

Part III Identity Synchronization for Windows Appendixes

Appendix A Using the Identity Synchronization for Windows Command Line Utilities

Identity Synchronization for Windows enables you to perform a variety of tasks from the command line. This appendix explains how to execute the Identity Synchronization for Windows command line utilities to perform different tasks. The information is organized into the following sections:

Common Features

The Identity Synchronization for Windows command line utilities share the following features:

Common Arguments to the Idsync Subcommands

This section describes the arguments (options) that are common to most of the command line utilities. The information is organized into the following tables:

Table A–1 Arguments Common to All Subcommands

Argument 

Description 

-h Configuration Directory-hostname

Specifies the configuration directory hostname. This argument defaults to the values specified during Core installation. 

-p Configuration Directory-port

Specifies the configuration directory LDAP port number. 

-D bind-DN

Specifies the configuration directory bind distinguished name (DN). This argument defaults to the values specified during Core installation. 

-w bind-password | -

Specifies the configuration directory bind password. The - value reads the password from standard input (STDIN).

-s rootsuffix

Specifies the configuration directory rootsuffix. Where rootsuffix is a distinguished name such as dc=example,dc=com. This argument defaults to the values specified during Core installation.

-q configuration_password | -

Specifies the configuration password. The - value means the password will be read from standard input (STDIN).

This argument is mandatory for all subcommands except prepds.

Table A–2 SSL-Related Arguments Common to All Subcommands

Argument 

Description 

-Z

Specifies that SSL be used to provide secure communication. Provides certificate-based client authentication when connecting to the configuration directory accessing the command line interface or the preferred/secondary Directory Servers.

-P cert-db-path

Specifies the path and file name of the client’s certificate database.

This certificate database must contain the CA certificate used to sign the Directory Server’s certificate database. 

If you specify -Z but do not use -P, the cert-db-path defaults to current-working-directory /cert8.db.

Note: If Identity Synchronization for Windows does not find the certificate database file in the specified directory, the program creates an *empty* database in that directory, which consists of three files: cert8.db, key3.db, and secmod.db.

-m secmod-db-path

Specifies the path to the security module database. For example: 

/var/Sun/MPS/slapd-serverID /secmod.db

Specify this argument only if the security module database is in a different directory than the certificate database itself. 

Table A–3 Configuration Directory Arguments

Argument 

Description 

-a ldap_filter

Use with forcepwchg and resync subcommands

Specifies the LDAP filter to use when retrieving users from the source SULs, and allows the operation to retrieve a focused subset of users from the directory source, prior to determining whether the users fall within the specified SULs.

-f filename

Use with export10cnf, importcnf, and resync subcommands

Specifies the name of a Configuration XML Document file. 

-n 

Use with forcepwchg, importcnf, and resetconn subcommands

Runs in safe mode so you can preview the effects of an operation with no actual changes. 

Entering Passwords

Wherever a password argument is required (such as -w bind-password or -q configuration_password), you can use the “ -” argument to tell the password program to read the password from STDIN.

If you use the “-” value for multiple password options, idsync will prompt you for passwords based on the arguments’ order.

In this case, the program would expect the bind-password first, and then for the configuration-password.

Getting Help

You can use one of the following commands to display usage information about idsync or any of its subcommands in the command Console:

For usage information

Using the idsync command

You use the idsync command and subcommands to execute the Identity Synchronization for Windows command line utility.


Note –

The idsync command converts all DN-valued arguments (such as bind DN or suffix name) from the character set specified for that window to UTF-8 before sending the arguments to Directory Server.

Do not use backslashes as escape characters in suffix names.

To specify UTF-8 characters on Solaris and on Linux, your terminal window must have a locale based on UTF-8. Make sure that the environmental variable’s LC_CTYPE and LANG.are set correctly.


Unless specifically noted otherwise, you can run the idsync command with subcommands using either of the following methods:

Table A–4 Quick Reference to idsync Subcommands

Subcommand 

Purpose 

certinfo

Displays certificate information based on your configuration and SSL settings (see Using certinfo)

changepw

Changes the Identity Synchronization for Windows configuration password (see Using changepw)

importcnf

Imports an exported Identity Synchronization for Windows version 1.0 configuration XML document (see Using importcnf)

prepds

Prepares a Sun Java System Directory Server source for use by Identity Synchronization for Windows (see Using prepds)

printstat

Displays a list of steps you must perform to complete the installation/configuration process. Also provides the status of installed connectors, the system manager, and the Message Queue (see Using printstat)

resetconn

Resets connector states in the configuration directory to uninstalled (see Using resetconn)

resync

Links and resynchronizes existing users or groups and pre-populates directories as part of the installation process (see Using resync)

groupsync

Synchronizes group information between users and groups from one directory source to another (see Using groupsync)

accountlockout

Synchronizes account lockout and unlockout between Directory Server and Active Directory sources (see Using accountlockout)

dspluginconfig

Configures and unconfigures Directory Server plugin on a specified host (see Using dspluginconfig)

startsync

Starts synchronization (see Using startsync)

stopsync

Stops synchronization (see Using stopsync)

Using certinfo

You can use the certinfo subcommand to display certificate information based on your configuration and SSL settings. This information can help you determine which certificates must be added for each connector and/or Directory Server Plug-in certificate database.

To display certificate information, open a terminal window (or Command Window) and type the idsync certinfo command as follows:

idsync certinfo [bind-DN] -w bind-password | - 
[-h Configuration Directory-hostname] [-p Configuration Directory-port-no] 
[-s rootsuffix] -q configuration_password [-Z] 
[-P cert-db-path] [-m secmod-db-path]

Note –

Because the certinfo subcommand does not have access to the connectors’ and Directory Server’s certificate databases, some of the required steps it lists might have already been performed.


For example:

idsync certinfo -w admin-password -q configuration-password

Note –

For detailed information about the certinfo arguments, review Common Arguments to the Idsync Subcommands.


Using changepw

You can use the changepw subcommand to change the Identity Synchronization for Windows configuration password.

ProcedureTo Change the Configuration Password for Identity Synchronization for Windows:

  1. Stop all Identity Synchronization for Windows processes (for example, System Manager, Central Logger, Connectors, Console, Installers/Uninstallers).

  2. After stopping all the processes, back up the ou=Services tree by exporting the configuration directory toldif.

  3. Type theidsync changepw command as follows:

    idsync changepw [-D bind-DN] -w bind-password | - 
    [-h Configuration Directory-hostname] [-p Configuration Directory-port-no] 
    [-s rootsuffix] -q configuration_password 
    [-Z] [-P cert-db-path] [-m secmod-db-path] 
    -b new password | - [-y]

    For example:


    idsync changepw -w admin password -q old config password -b -q new config password
    

    The following arguments are unique to changepw:

    Argument 

    Description 

    -b password

    Specifies a new configuration password. The - value reads the password from standard input (STDIN).

    [-y]

    Does not prompt for command confirmation. 

  4. Respond to the messages that display in the terminal window. For example,


    Are you sure that want to change the configuration password (y/n)? yes
    Before restarting the system - 
    you must edit the $PSWHOME/resources/SystemManagerBootParams.cfg file
    and change the ’deploymentPassword’ to the new value.
    
    SUCCESS
  5. You must modify the SystemManagerBootParams.cfg file before restarting the system.

    The SystemManagerBootParams.cfg file in $PSWHOME\resources (where $PSWHOME is the isw-installation directory ) contains the configuration password the system manager uses to connect to the configuration directory.

    For example, you would change the password value as follows:

    From: Parameter name="manager.configReg.deploymentPassword" value=" oldpassword"/

    To: Parameter name="manager.configReg.deploymentPassword" value= "newpassword "/

  6. If the program reports any errors, restore the configuration directory using the ldif from Using changepw and then try again. The most likely reason for an error is that the Directory Server hosting the configuration directory became unavailable during the password change.

Using importcnf

After installing Core (Chapter 6, Installing Core), use the idsync importcnf subcommand to import your exported Identity Synchronization for Windows version 1.0 or 1.1 (SP1) configuration XML file, which contains Core configuration information.

To import your version 1.0 configuration XML file, open a terminal window (or Command Window) and type the idsync importcnf command as follows:

idsync importcnf [-D bind-DN] -w bind-password | - 
[-h Configuration Directory-hostname] [-p Configuration Directory-port-no] 
[-s rootsuffix] -q configuration_password [-Z] [-P cert-db-path] 
[-m secmod-db-path] -f filename [-n]

For example:

idsync importcnf -w admin_password -q configuration_password -f “MyConfig.cfg”

The following arguments are unique to importcnf:

Table A–5 idsync importcnf Arguments

Argument 

Description 

-f filename

Specifies the name of your configuration XML document. 

-n

Runs in safe mode so you can preview the effects of an operation with no actual changes. 


Note –

For detailed information about other importcnf arguments, review Common Arguments to the Idsync Subcommands.


After importing the version 1.0 configuration XML file, you must run prepds on all Directory Server sources configured for synchronization, (see Using prepds connectors and subcomponents.

Using prepds

You use the console or prepds subcommand to prepare a Sun Java System Directory Server source for use by Identity Synchronization for Windows. You must run prepds before installing the Directory Server Connector.

Running the idsync prepds subcommand applies the appropriate ACI to the cn=changelog entry, which is the root node of the Retro-Changelog database.

If you are preparing a preferred master Directory Server for use by Identity Synchronization for Windows, you must provide Directory Manager credentials.

The Directory Manager user is a special user on Directory Server who has full rights anywhere inside the Directory Server instance. (ACI does not apply to Directory Manager users.)

For example, only the Directory Manager can set the access control for the Retro-Changelog database, which is one of the reasons why Identity Synchronization for Windows requires Directory Manager credentials for the preferred master server.


Note –

If you re-create the Retro-Changelog database for the preferred Sun directory source for any reason, the default access control settings will not allow the Directory Server Connector to read the database contents.

To restore the access control settings for the Retro-Changelog database, run idsync prepds or click the Prepare Directory Server button after selecting the appropriate Sun directory source in the Console.

You can configure your system to automatically remove (or trim) Changelog entries after a specified period of time. From the command line, modify the nsslapd-changelogmaxage configuration attribute in cn=Retro Changelog Plug-in, cn=plugins, cn=config:

nsslapd-changelogmaxage: IntegerTimeunit

Where:

Be sure to plan your Identity Synchronization for Windows configuration before running idsync prepds because you must know which hosts and suffixes you will be using.

Running idsync prepds on a Directory Server suffix where the Directory Server Connector and Plug-in are already installed, configured, and synchronizing will result in a message asking you to install the Directory Server Connector. Disregard this message.


To prepare a Sun Java System Directory Server source, open a terminal window (or a Command Window) and type the idsync prepds command as follows:

For single host:

idsync prepds [-h <hostname>] [-p <port>] [-D <Directory Manager DN>] -w <password> 
-s <database suffix> [-x] [-Z] [-P <cert db path>] [-m <secmod db path>]

For multiple hosts:

idsync prepds -F <filename of Host info> -s <root suffix> [-x] [-Z] 
[-P <cert db path>][-m <secmod db path>] [-3]

For example:

idsync prepds -D “cn=Directory Manager” -w preferred master password 
-h preferred-host -p 389 -s dc=example,dc=com -j “secondary host” -r 389 
-E “cn=Administrator” -u secondary master password -s dc=example,dc=com

Note –

The -h, -p, -D, -w, and -s arguments are redefined (as described in the following table) for the prepds subcommand only. In addition, the -q argument does not apply.


Using prepds describes the arguments that are unique to idsync prepds.

Table A–6 prepds Arguments

Argument 

Description 

-h name

Specifies the DNS name of the Directory Server instance serving as the preferred host. 

-p port

Specifies port number for Directory Server instance serving as preferred host. (Default is 389.)

-j name (optional)

Specifies the DNS name of the Directory Server instance serving as the secondary host (applicable in a Sun Java System Directory Server 5 2004Q2 multimaster replicated (MMR) environment). 

-r port (optional)

Specifies a port for the Directory Server serving as the secondary host (applicable in a Sun Java System Directory Server 5 2004Q2 multimaster replicated (MMR) environment). (Default is 389)

-D dn

Specifies the distinguished name of the Directory Manager user for the preferred host. 

-w password

Specifies a password for the Directory Manager user for the preferred host. The - value reads the password from standard input (STDIN).

-E admin-DN

Specifies the distinguished name of the Directory Manager user for the secondary host. 

-u password

Specifies a password for the Directory Manager user for the secondary host. The - value reads the password from standard input (STDIN).

-s rootsuffix

Specifies the root suffix to use for adding an index (root suffix where you will be synchronizing users). 

Note: The database name of the Preferred and Secondary hosts may vary, but the suffix will not. Consequently, the program can find the database name of each host and use it to add the indexes.

-x

Does not add equality and presence indexes for dspswuserlink attribute to the database.

-F filename of Host info

Specifies the filename containing the host information in case of multiple hosts environment. 

If you are running idsync prepds in a replicated environment, (for example, where you have a preferred master, a secondary master, and two consumers), you only need to run idsync prepds once for the preferred and secondary masters.

ProcedureTo run idsync prepds

  1. Ensure that Directory Server replication is up and running (if applicable.)

  2. Run idsync prepds from the Console or from the command line, for example:


    idsync prepds -h M1.example.com -p 389 -j M2.example.com -r 389.

    Running the idsync prepds command on M1 accomplishes the following:

    • Enables and extends the RCL to capture more attributes ( dspswuserlink and so forth)

      RCL is required on M1 only.

    • Extends schema.

    • Adds uid=pswconnector,suffix user with ACIs.

    • Adds indexes to the dspswuserlink attribute, which puts Directory Server in read-only mode temporarily until the indexing is done.

      You can add indexes later to avoid downtime, but you must add indexes before installing the Directory Server Connector.

    Adds indexes on M2.


    Note –
    • Replication ensures that Identity Synchronization for Windows copies schema information and the uid=pswconnector from the preferred master to the secondary master and both consumers.

    • You must install the Directory Server Connector once. You must install the Directory Server Plug-in in all directories.

    • Indexing is required on the preferred and the secondary masters only. (Replication does not push the indexing configuration from the preferred master to the secondary master.)


Using printstat

You can use the printstat subcommand to:

Using resetconn

You can use the resetconn subcommand to reset connector states in the configuration directory to uninstalled. For example, if a hardware failure prevents you from uninstalling a connector, use resetconn to change the connector’s status to uninstalled so you can reinstall that connector.


Note –

The resetconn subcommand is intended to be used only in the event of hardware or uninstaller failures.


To reset the state of connectors from the command line, open a terminal window (or a Command Window) and type the idsync resetconn command as follows:

idsync resetconn [-D bind-DN] -w bind-password\> | - 
[-h Configuration Directory-hostname] [-p Configuration Directory-port-no] 
[-s rootsuffix] -q configuration_password [-Z] [-P cert-db-path] 
[-m secmod-db-path] -e directory-source-name [-n]

For example:

idsync resetconn -w admin password -q configuration_password -e “dc=example,dc=com“

Using prepds describes the arguments that are unique to resetconn:

Table A–7 idsync resetconn Arguments

Argument 

Description 

-e dir-source

Specifies the name of the directory source to reset. 

-n

Runs in safe mode so you can preview the effects of an operation with no actual changes. 


Note –

idsync printstat can be used to find directory source names.

For detailed information about the other resetconn arguments, review Common Arguments to the Idsync Subcommands.


Using resync

You can use the resync subcommand to bootstrap deployments with existing users. This command uses administrator-specified matching rules to


Note –

For more detailed information about linking and synchronizing users, see Chapter 4, Understanding the Product.


To resynchronize existing users and to pre-populate directories, open a terminal window (or a Command Window) and type the idsync resync command as follows:

idsync resync [-D bind-DN] -w bind-password | - 
[-h Configuration Directory-hostname] [-p Configuration Directory-port-no] 
[-s rootsuffix] -q configuration_password [-Z] [-P cert-db-path] 
[-m secmod-db-path] [-n] [-f xml filename for linking] [-k] [-a ldap-filter] 
[-l sul-to-sync] [-o Sun | Windows] [-c] [-x] 
[-u][-i ALL_USERS | NEW_USERS | NEW_LINKED_USERS]

For example:

idsync resync -w admin password -q configuration_password

Using resync describes the arguments that are unique to resync:

Table A–8 idsync resync Usage

Argument 

Meaning

-f filename

Creates links between unlinked user entries using one of the specified XML configuration files provided by Identity Synchronization for Windows (see Appendix B, Identity Synchronization for Windows LinkUsers XML Document Sample )

-k

Creates links between unlinked users only (does not create users or modify existing users) 

-a ldap-filter

Specifies an LDAP filter to limit the entries to be synchronized. The filter will be applied to the source of the resynchronization operation. For example, if you specify idsync resync -o Sun -a “uid=*” all Directory Server users that have a uid attribute will be synchronized to Active Directory.

-l sul-to-sync

Specifies individual Synchronization User Lists (SULs) to resynchronize 

Note: You can specify multiple SUL IDs to resynchronize multiple SULs or, if you do not specify any SUL IDs, the program will resynchronize all of your SULs.

-o (Sun | Windows)

Specifies the source of the resynchronization operation 

  • Sun: Sets attribute values for Windows entries to corresponding attribute values in Sun Java System Directory Server directory source entries.

  • Windows: Sets attribute values for Sun Java System Directory Server entries to corresponding attribute values in Windows directory source entries.

    (Default is Windows)

-c

Creates a user entry automatically if the corresponding user is not found at destination 

  • Randomly generates a password for users created in Active Directory or Windows NT

  • Automatically creates a special password value ((PSWSYNC) *INVALID PASSWORD*) for users created in Directory Server (unless you specify the -i option)

-i (ALL_USERS | NEW_USERS | NEW_LINKED_USERS)

Resets passwords for user entries synchronized in the Sun directory sources, forcing password synchronization within the current domain for those users the next time the user password is required. 

  • ALL_USERS: Forces on-demand password synchronization for all synchronized users

  • NEW_USERS: Forces on-demand password synchronization for newly created users only

  • NEW_LINKED_USERS: Forces on-demand password synchronization for all newly created and newly linked users

-u 

Only updates the object cache. No entries are modified. 

This argument updates the local cache of user entries for a Windows directory source only, which prevents pre-existing Windows users from being created in Directory Server. If you use this argument, Windows user entries are not synchronized with Directory Server user entries. This argument is valid only when the resync source is Windows. 

-x 

Deletes all destination user entries that do not match a source entry. 

-n

Runs in safe mode so you can preview the effects of an operation with no actual changes. 


Note –

Using groupsync

You can use the groupsync subcommand to synchronize groups between Active Directory and Directory Server.

To enable or disable the Group Synchronization, type idsync groupsync command.

For example:

idsync groupsync -{e/d} -D <bind DN> -w <bind password> [-h <CD hostname>] 
[-p <CD port no>] -s <rootsuffix> [-Z] -q <configuration password> -t <AD group type>
Table A–9 groupsync arguments

Argument 

Meaning 

-{e/d}

Select e for enabling , and d for disabling the group synchronization. 

-t 

Specifies the group type at Active Directory. For example, it can be selected as either of "distribution" or "security" 

Using accountlockout

You can use the accountlockout subcommand to synchronize account lockout and unlockout between Active Directory and Directory Server.

To enable or disable the account lockout, type idsync accountlockout command.

For example:

idsync accountlockout -{e/d} -D <Directory Manager DN> -w <bind-password> 
-h <Configuration Directory-hostname> -p <Configuration Directory-port-no> 
-s <rootsuffix> [-Z] [-P <cert db path>] [-m <secmod db path>] 
-q <configuration password> -t <max lockout attempts>
Table A–10 accountlockout arguments

Argument 

Meaning 

-{e/d}

Select e for enabling , and d for disabling the account lockout synchronization. 

-t 

Specifies the maximum number of lockout attempts that Active Directory Connector performs. 

Using dspluginconfig

You can use the dspluginconfig subcommand to configure or unconfigure Directory Server plugin on a specified Directory Server data source.

To configure or unconfigure the Directory Server plugin, type idsync dspluginconfigcommand.

For example:

idsync dspluginconfig -{C/U} -D <bind DN> -w <bind password | -> 
[-h <CD hostname>] [-p <CD port no>] [-s <configuration suffix>] 
[-Z] [-P <cert db path>] [-m <secmod db path> ] [-d <ds plugin hostname>] 
[-r <ds plugin port>] [-u <ds plugin user>] [-x <ds plugin user password>] 
[-o <database suffix>]  [-q <configuration password | ->]
Table A–11 dspluginconfig arguments

Argument 

Meaning 

-{C/U}

Select C for configuring and U for unconfiguring the Directory Server plugin. 

-d 

Host name of the Directory Server data source where the plugin needs to be configured 

-r 

Port number of the Directory Server data source where the plugin needs to be configured 

-u 

Administrator of the Directory Server data source where the plugin needs to be configured 

-x 

Password of the administrator of the Directory Server data source where the plugin needs to be configured 

-o 

Data suffix of the Directory Server data source. 

Using startsync

You can use the startsync subcommand to start synchronization from the command line.

To start synchronization, open a terminal window (or a Command Window) and type the idsync startsync command as follows:

idsync startsync [-D bind-DN] -w bind-password | - 
[-h Configuration Directory-hostname] [-p Configuration Directory-port-no] 
[-s rootsuffix] -q configuration_password [-Z] 
[-P cert-db-path] [-m secmod-db-path]

For example:

idsync startsync -w admin password -q configuration_password

Using startsync describes the arguments that are unique to startsync.

Table A–12 idsync startsync Arguments

Argument 

Description 

[-y]

Does not prompt for command confirmation. 


Note –

For detailed information about the other startsync arguments, review Common Arguments to the Idsync Subcommands.


Using stopsync

You can use the stopsync subcommand to stop synchronization from the command line.

To stop synchronization, open a terminal window (or a Command Window) and type the idsync stopsync command as follows:

idsync stopsync [-D bind-DN] -w bind-password | - 
[-h Configuration Directory-hostname] [-p Configuration Directory-port-no] 
[-s rootsuffix] -q configuration_password [-Z] 
[-P cert-db-path] [-m secmod-db-path]

For example:

idsync stopsync -w admin password -q configuration_password

Note –

For detailed information about the stopsync arguments, review Common Arguments to the Idsync Subcommands.


Using the forcepwchg Migration Utility

Users who change their passwords during migration will have different password in Windows NT and the Directory Server. You can use the forcepwchg utility to require a password change for users who changed their passwords during the Identity Synchronization for Windows version 1.0 to version 6.0 migration process.


Note –

The forcepwchg utility ships with Windows packages only.


Before using forcepwchg you must verify the following:

ProcedureTo Execute the forcepwchg Command line Utility

  1. Open a Command Prompt window and cd to the Windows migration directory on the host where you are performing the migration. (The Identity Synchronization for Windows 1.0 NT components such as connector, Change Detector DLL, and Password Filter DLL must be installed on the PDC host.)

  2. From themigration directory, type


    java -jar forcepwchg.jar [-n] [-a] [-t <
    time_specification\>]
    

    For example,


    forcepwchg.jar -n -a forcepwchg.jar -t 33m

    Using the forcepwchg Migration Utility describes the arguments that are unique to forcepwchg:

    Option 

    Description 

    -n 

    Specifies preview mode. In the preview mode, the utility prints out the names of all normal users except:

    • Built-in accounts (Administrator and Guest) if you specify the -a argument.

    • Users who changed passwords during the time specified using the -t argument.

      In preview mode, any user can execute forcepwchg. In non-preview mode, only the Administrator can execute forcepwchg.

    -a 

    Requires all users (except Administrator and Guest) to change their passwords. You cannot use this argument if you are using the -t argument.

    -t time_specification

    Forces all users who changed passwords in the past time specification to change their passwords. Where time specification can have the following form:

    • number: Number of seconds (for example, -t 30)

    • number m: Number of minutes (for example, -t 25m)

    • number h: Number of hours (for example, -t 6h)

      For example, if you specify forcepwchg -t 6h, all users who changed passwords within the last six hours will be required to change their password again.

    -? 

    Prints out usage information. 

Appendix B Identity Synchronization for Windows LinkUsers XML Document Sample

This appendix provides two sample XML configuration documents that you can use with the idsync resync subcommand to link existing users in your deployment.

Both of the following files are available in the samples1 subdirectory where you installed Core:

You can modify the samples to suit your environment. Both files contain comments that explain how to modify the samples to link your users — including how to link users in multiple SULs.

Sample 1: linkusers-simple.cfg

<!--
    Copyright 2004 Sun Microsystems, Inc. All rights reserved
    Use is subject to license terms.
--\>
<!--
    This xml file is used to link Windows and
    Sun Directory Server users from the commandline.
    It is passed to the ’idsync resync’
    script as the -f option. This is a simple file
    that links users in the SUL1 synchronization user list
    that have the same login name, that is the Directory Server
    uid attribute matches the Active Directory
    samaccountname attribute. For more complex 
    matching rules, see the linkusers.cfg sample.
--\>

<UserLinkingOperationList\>
 <UserLinkingOperation parent.attr="UserLinkingOperation"
           sulid="SUL1"\>
   <UserMatchingCriteria parent.attr="UserMatchingCriteria"\>
    <AttributeMap parent.attr="AttributeMap"\>
      <AttributeDescription parent.attr="SunAttribute"
                name="uid"/\>
      <AttributeDescription parent.attr="WindowsAttribute"
                name="samaccountname"/\>
      </AttributeMap\>
      </UserMatchingCriteria\>
   </UserLinkingOperation\>
</UserLinkingOperationList\>

Sample 2: linkusers.cfg


<?xml version =”1.0” encoding=”UTF-8”?\>
<!--

    Copyright 2004 Sun Microsystems, Inc.
    All rights reserved
    Use is subject to license terms.
--\>
<!--
    This xml file is used to link Windows
    and Sun Directory Server users from
    the command line.  It is passed to the 
    \qidsync resync\q script as the -f option.
--\>
<!--
    The following parameters allowLinkingOutOfScope:
    if true, then Windows users can be
    linked to Sun Directory Server users
    that are outside of the users\q Synchronization
    User List. Default is false.
--\>
<UserLinkingOperationList allowLinkingOutOfScope="false"\>


<!--
    UserLinkingOperation encapsulates the configuration
    of a single SUL to link. It includes the SUL ID
    and a list of attributes to match.
    A separate UserLinkingOperation must
    be specified for each SUL being linked.
--\>
<UserLinkingOperation parent.attr="UserLinkingOperation" sulid="SUL1"\>


<!--
    UserMatchingCriteria encapsulates a 
    list of attributes that must match for a user to be linked. --\>
<!--
    For two users to match using this UserMatchingCriteria,
    they must have the same givenName and the same sn. --\>
<UserMatchingCriteria parent.attr="UserMatchingCriteria"\>
    <AttributeMap parent.attr="AttributeMap"\>
    <AttributeDescription parent.attr="SunAttribute" name="sn"/\>
    <AttributeDescription parent.attr="WindowsAttribute" name="sn"/\>
    </AttributeMap\>    <AttributeMap parent.attr="AttributeMap"\>
    <AttributeDescription parent.attr="SunAttribute" name="givenName"/\
    <AttributeDescription parent.attr="WindowsAttribute"
    name="givenName"/\>    </AttributeMap\></UserMatchingCriteria\>

<!--
    Multiple UserMatchingCriteria can be specified for a single SUL.
    They are treated as a logical OR.  In this example, 
    the givenName\qs and sn\qs must match (see above)) OR
    (the employee(Number|ID) must match),
    for the user to be linked.  Notice that attribute
    that is specified, employeeNumber,
    is the name of the DS attribute. --\>
<!--
    This UserMatchingCriteria is commented out because
    employeeNumber is not an indexed attribute in DS.
    All attributes used in a UserMatchingCriteria
     should be indexed.
    <UserMatchingCriteria parent.attr="UserMatchingCriteria"\>
      <AttributeMap parent.attr="AttributeMap"\>
         <AttributeDescription parent.attr=
         "SunAttribute" name="employeeNumber"/\>
           <AttributeDescription parent.attr=
           "WindowsAttribute" name="employeeID"/\>
       </AttributeMap\>
    </UserMatchingCriteria\>
--\>
</UserLinkingOperation\>
<!--
    When multiple SULs are linked, a separate UserLinkingOperation 
    is specified for each.
    As shown here, each UserLinkingOperation can use different
    UserMatchingCriteria: in this example, users in SUL2 are
    only linked if their sn and employeeNumber match.
    Note: this UserLinkingOperation is currently 
    commented out because the example configuration
    only has a single SUL.
  <UserLinkingOperation parent.attr="UserLinkingOperation" sulid="SUL2"\>
    <UserMatchingCriteria parent.attr="UserMatchingCriteria"\>
      <AttributeMap parent.attr="AttributeMap"\>
          <AttributeDescription parent.attr="SunAttribute" name="sn"/\>
          <AttributeDescription parent.attr="WindowsAttribute" name="sn"/\>
       </AttributeMap\>
          <AttributeMap parent.attr="AttributeMap"\>
            <AttributeDescription parent.attr=
            "SunAttribute" name="employeeNumber"/\>
             <AttributeDescription parent.attr=
             "WindowsAttribute" name="employeeID"/\>
       </AttributeMap\>
    </UserMatchingCriteria\>
</UserLinkingOperation\>
--\>
</UserLinkingOperationList\>
      

Appendix C Running Identity Synchronization for Windows Services as Non-Root on Solaris

You must have root privileges to install and to run Identity Synchronization for Windows services on Solaris and Red Hat systems.

However, after installing the product you can configure the software to run the program services as a non-root user.

Running Services as a Non-root User


Note –

To run services as non-root, you must change the permissions for all directories under the Identity Synchronization for Windows instance directory. The default directory is /var/opt/SUNWisw.


ProcedureTo Run services as a Non-root User

Although you must be root to install and to run Identity Synchronization for Windows services, you can configure the software to run the program services as a non-root user.

  1. (Optional) Use the UNIX useradd command to create a user account for Identity Synchronization for Windows.

    You also can use a nobody user to run services. The remaining examples in this procedure assume you created a user called iswuser.

  2. To install a Sun Java System Directory Server Connector, you must choose a non-privileged port for the Connector during installation.

    For example, ports larger than 1024 are acceptable. Port 1389 is recommended for LDAP when the server is running as a non-root user. Port 1636 is recommended for LDAP over SSL.


    Note –

    You must execute all commands in the remaining steps as root.


  3. After installing all components, execute the following command to stop Identity Synchronization for Windows:


    /etc/init.d/isw stop
    
  4. You must update the ownership of the instance directory. For example, if you installed the product in/var/opt/SUNWisw.


    chown -R iswuser /var/opt/SUNWisw
    

    chown -R iswuser /opt/SUNWisw
    
  5. In a text editor, open the/etc/init.d/isw file and replace the following line:


    "$EXEC_START_WATCHDOG" "$JAVA_PATH" "$INSTALL_DIR" "$CONFIG_DIR"

    with the following:


    su iswuser -c "$EXEC_START_WATCHDOG '$JAVA_PATH' '$INSTALL_DIR' '$CONFIG_DIR'"
  6. Execute the following command to restart the service:


    /etc/init.d/isw start
    
  7. Execute the following command to verify that the components are running using the assigned user’s userid:


    ps -ef | grep iswuser
    

Appendix D Defining and Configuring Synchronization User Lists for Identity Synchronization for Windows

This appendix provides supplemental information about Synchronization User List (SUL) definitions and explains how to configure multiple domains. The information is organized as follows:

Understanding Synchronization User List Definitions

Every Synchronization User List (SUL) contains two definitions — one to identify which Directory Server users to synchronize and the other to identify which Windows users to synchronize.

Each definition identifies which users in a directory to synchronize, which users to exclude from synchronization, and where to create new users.


Note –

The objectclasses you select using the Identity Synchronization for Windows Console also determine which users will be synchronized. The program synchronizes only those users that have the selected objectclass, which includes any users that have a subclass of the selected objectclass.

For example, if you select the organizationalPerson objectclass, then Identity Synchronization for Windows will synchronize users with the inetorgperson objectclass because it is a subclass of the organizationalPerson objectclass.


Understanding Synchronization User List Definitions describes the components of an SUL definition:

Table D–1 SUL Definition Components

Component 

Definition 

Applicable 

   
   

Sun 

AD 

NT 

Base DN

Defines the parent LDAP node of all users to be synchronized. 

A Synchronization User List base DN includes all users in that DN — unless the users are excluded by the Synchronization User List’s filter or the user’s DN is matched in a more specific Synchronization User List. For example, ou=sales,dc=example,dc=com.

Yes 

Yes 

No 

Filter

Defines an LDAP-like filter used to include or exclude users from a Synchronization User List. The filter can include the &, |, !, =, and * operators. The \>= and <= operators are not supported. All comparisons are done using case-insensitive string comparisons.

For example, (& (employeeType=manager)(st=CA)) will include managers in California only.

Yes 

Yes 

Yes 

Creation Expression

Defines the parent DN and naming attribute of newly created users (applicable only when you enable creates). 

The creation expression must include the base DN of the Synchronization User List. For example, cn=%cn%,ou=sales,dc=example,dc=com. (Where the %cn% token is replaced with a value from the user entry being created.)

Yes 

Yes 

No 


Note –

To synchronize users in a Sun Java System Directory Server with multiple Active Directory domains, you must define at least one SUL for each Active Directory domain.

When Group Synchronization is enabled, the following are important:

  1. The creation expression supported at Active Directory is cn=%cn%.

  2. The creation expression must contain valid attribute names belonging to the group objectclass since the creation expression is common to both user as well as group.

    For example:

    The attribute sn is not part of the groupofuniquenames objectclass at the Directory Server. Hence the following creation expression would be invalid for a group object. (Though it would work fine for user.)


    cn=%cn%.%sn%
    
  3. The attribute used in the creation expression must be provided with a value for every user/group entry created. If the value is not provided then the user/group object will not synchronize and an appropriate message will be logged in the central log.


When you define multiple SULs, Identity Synchronization for Windows determines membership in an SUL by iteratively matching each SUL definition. The program examines the SUL definitions with more-specific base DNs first. For example, the program tests a match against ou=sales,dc=example,dc=com before testing dc=example,dc=com.

If two SUL definitions have the same base DN and different filters, then Identity Synchronization for Windows cannot determine automatically which filter should be tested first, so you must use the Resolve Domain Overlap feature to order the two SUL definitions. If a user matches the base DN of an SUL definition but does not match any filters for that base DN, then the program will exclude that user from synchronization — even if that user matches the filter for a less-specific base DN.

Configuring Multiple Windows Domains

To support synchronizing multiple Windows domains to the same Directory Server container (such as ou=people,dc=example,dc=com), Identity Synchronization for Windows uses “synthetic” Windows attributes that contain domain information.

ProcedureTo Configure Multiple Windows Domains

  1. Users in the Active Directory east.example.com domain will be synchronized to the Directory Server in ou=people,dc=example,dc=com.

  2. Users in the Active Directory west.example.com domain will be synchronized to the Directory Server in ou=people,dc=example,dc=com.

  3. Users in the Windows NT NTEXAMPLE domain will be synchronized to the Directory Server in ou=people,dc=example,dc=com.

    When you create or modify a Directory Server user, the program uses the SUL filters to determine in which Windows domain to synchronize the user (because each Directory Server SUL has the same base DN, ou=people,dc=example,dc=com ). The activedirectorydomainname and user_nt_domain_name attributes make constructing these filters easy.

    To construct a filter from the Attributes tab on the Console:

  4. Map the Directory Server destinationindicator attribute to the Active Directory activedirectorydomainname attribute and to the Windows NT user_nt_domain_name attribute.

  5. Configure one SUL for each Windows domain as follows:

    EAST_SUL

    Sun Java System Directory Server definition 
            Base DN:    ou=people,dc=example,dc=com
            Filter:    destinationindicator=east.example.com
            Creation Expression:  cn=%cn%,ou=people,dc=example,dc=com
    Active Directory definition (east.example.com)
            Base DN:    cn=users,dc=east,dc=example,dc=com
            Filter:     <none\>
            Creation Expression:  cn=%cn%,cn=users,dc=east,dc=example,dc=com

    WEST_SUL

    Sun Java System Directory Server definition
            Base DN:ou=people,dc=example,dc=com
            Filter:  destinationindicator=west.example.com
            Creation Expression: cn=%cn%,ou=people,dc=example,dc=com
    Active Directory definition (west.example.com)
            Base DN:  cn=users,dc=west,dc=example,dc=com
            Filter:<none\>
            Creation Expression:  cn=%cn%,cn=users,dc=west,dc=example,dc=com

    NT_SUL

    Sun Java System Directory Server definition
            Base DN:  ou=people,dc=example,dc=com
            Filter:  destinationindicator=NTEXAMPLE
            Creation Expression:  cn=%cn%,
            ou=people,dc=example,dc=com
    Windows NT definition (NTEXAMPLE)
            Base DN:  NA
            Filter:  <none\>
            Creation Expression:  NA

    Notice that each Directory Server SUL definition has the same base DN and creation expression, but the filters indicate the domain of the corresponding Windows user entry.

    To further illustrate how these settings allow Directory Server user entries to synchronize with separate Windows domains, consider this test case:

  6. Create cn=Jane Test,cn=users,dc=east,dc=example,dc=com in the Active Directory east.example.com domain.

  7. Identity Synchronization for Windows creates the user entry cn=Jane Test,ou=people,dc=example,dc=comin the Directory Server with destinationindicator=east.example.com.

  8. Modify thecn=Jane Test,ou=people,dc=example,dc=com entry in the Directory Server.

  9. Because Jane Test’s destinationindicator attribute is east.example.com, her entry will match the EAST_SUL Synchronization User List filter, and the modification will be synchronized to the east.example.com Active Directory domain.

    This example assumes that Identity Synchronization for Windows is synchronizing user creations from Windows to the Directory Server. If this is not the case, you can run the idsync resync command to set the destinationindicator attribute.


    Note –

    When you use idsync resync -f in a deployment with multiple SULs, you probably will have to set the allowLinkingOutOfScope option to true in the linking configuration file. See Appendix B, Identity Synchronization for Windows LinkUsers XML Document Sample


    The example uses an existing attribute in inetorgperson, destinationIndicator, which might be used for other purposes. If this attribute is already in use or a you select a different objectclass, you must map some attribute in the user’s Directory Server entry to the user_nt_domain_name and/or the activedirectorydomainname attribute(s). The Directory Server attribute you choose to hold this value must be in the objectclass you are using for the rest of the attribute mapping configuration.

    If there are no unused attributes to hold this domain information, you must create a new objectclass to include a new domain attribute and all other attributes you will be using with Identity Synchronization for Windows.

Appendix E Identity Synchronization for Windows Installation Notes for Replicated Environments

Identity Synchronization for Windows 6.0 supports synchronizing users in a single replicated suffix.


Note –

This appendix summarizes procedures used to configure and secure a multimaster replication (MMR) deployment. The information is taken directly from the Sun Java System Directory Server Enterprise Edition 6.2 Administration Guide — and is not Identity Synchronization for Windows - specific.

Designing and implementing an MMR deployment is complex. Refer to the Sun Java System Directory Server Enterprise Edition 6.2 Deployment Planning Guide to plan your deployment and the Sun Java System Directory Server Enterprise Edition 6.2 Administration Guide to implement the deployment.


This appendix is organized into the following sections:

Configuring Replication


Note –

In multimaster replication (MMR) environments, Identity Synchronization for Windows allows you to specify a preferred and secondary master servers for any given Sun directory source.

Directory Server supports n-way MMR (where you can change the replicated database at any of the 'n' masters configured). When you install the plug-in at the preferred master, you must select the Other host type and enter Directory Server instance's parameters manually during plug-in installation.


The following steps assume you are replicating a single suffix. If you are replicating more than one suffix, you may configure them in parallel on each server. In other words, you may repeat each step to configure replication on multiple suffixes.

ProcedureTo Configure any Replication Topology

  1. Define a replication manager entry on all servers except single masters (or use the default replication manager on all servers.)

  2. On all servers containing a dedicated consumer replica:

    1. Create an empty suffix for the consumer replica.

    2. Enable the consumer replica on the suffix through the replication wizard.

    3. Optionally, configure the advanced replica settings.

  3. On all servers containing a hub replica, if applicable:

    1. Create an empty suffix for the hub replica.

    2. Enable the hub replica on the suffix through the replication wizard.

    3. Optionally, configure the advanced replica settings.

  4. On all servers containing a master replica:

    1. Choose or create a suffix on one of the masters that will be the master replica.

    2. Enable the master replica on the suffix through the replication wizard.

    3. Optionally, configure the advanced replica settings.

  5. Configure the replication agreements on all supplier replicas, in the following order:

    1. Between masters in a multimaster set.

    2. Between masters and their dedicated consumers.

    3. Between masters and hub replicas.

      Optionally, you can configure fractional replication at this stage.

  6. Configure replication agreements between the hub replicas and their consumers.

  7. For multimaster replication, initialize all masters from the same master replica containing the original copy of the data. Initialize the hub and consumer replicas.

Configuring Replication Over SSL


Note –

In this procedure, all references are chapters in the Sun Java System Directory Server Enterprise Edition 6.2 Administration Guide.


ProcedureTo Configure Directory Servers Involved in Replication so that all Replication Operations Occur Over an SSL Connection

  1. Configure both the supplier and consumer servers to use SSL.

    Refer to Chapter 11, “Managing Authentication and Encryption” for details.


    Note –
    • Replication over SSL will fail if the supplier server certificate is an SSL server-only certificate that cannot act as a client during an SSL handshake.

    • Replication over SSL is currently unsupported with self-signed certificates.


  2. If replication is not configured for the suffix on the consumer server, enable it as described in Chapter 8, “Enabling a Consumer Replica.”

  3. Follow the procedure in Chapter 8, “Advanced Consumer Configuration,” to define the DN of the certificate entry on the consumer as another replication manager.

  4. If replication is not configured for the suffix on the supplier server, enable it as described in Chapter 8, “Enabling a Hub Replica” or “Enabling a Master Replica.”

  5. On the supplier server, create a new replication agreement to send updates to the consumer on the secure SSL port. Follow the procedure in Chapter 8, “Creating Replication Agreements,” for detailed instructions. Specify a secure port on the consumer server and select the SSL option of either using a password or a certificate. Enter a DN for the SSL option that you chose, either a replication manager or a certificate.

    After you finish configuring the replication agreement, the supplier will send all replication update messages to the consumer over SSL and will use certificates if you chose that option. Customer initialization will also use a secure connection if performed through the console using an agreement configure for SSL.

Configuring Identity Synchronization for Windows in an MMR Environment

ProcedureTo Configure Identity Synchronization for Windows in an MMR Environment

  1. From the Identity Synchronization for Windows Console, specify a preferred master and secondary master servers for the suffix to be synchronized. (Review Creating a Sun Java System Directory Source)

    You do not have to provide information about other Directory Servers in your topology.

  2. Prepare the preferred master and secondary master servers from the Console or using the idsync prepds command line utility. (Review Preparing Sun Directory Source

    If you use the command line utility, you should prepare both servers in a single invocation by specifying arguments for both the preferred and secondary servers.

  3. Install the Directory Server Connector for the suffix replicated between these directories. (ReviewInstalling the Directory Server Connector)

  4. Configure the Directory Server Plug-in on the preferred master, the secondary masters, and every other Directory Server instance that manages users in the replicated suffix (Review Using dspluginconfig)