Sun Java System Identity Synchronization for Windows 1 2004Q3 Installation and Configuration Guide |
Chapter 2
Preparing for InstallationBefore installing Identity Synchronization for Windows 1 2004Q3 or before you migrate from version 1.0 to version 1 2004Q3, you should familiarize yourself with the installation and configuration process.
This chapter describes these processes and provides other information you may find helpful as you prepare to install the product. This information is organized into the following sections:
Installation RequirementsThis section describes the installation requirements for Identity Synchronization for Windows, which includes operating system versions, patches, and utilities for each platform.
Operating System Requirements
The following tables describe the operating system requirements for this release of Identity Synchronization for Windows:
Hardware Requirements
Your hardware (all platforms) must meet the following minimum requirements to run Identity Synchronization for Windows:
Sun Java System Software Requirements
Before you can install Identity Synchronization for Windows, you must install the following Sun Java System software components:
The patch fix enables delete functionality for Identity Synchronization for Windows 1 2004Q2 with Directory Server 5 2004Q2.
- For Solaris SPARC Package Format: Patch Number 117907-02 or higher
- For Solaris SPARC Compressed Archive Installations: Patch 5077789
- For Solaris x86 Package Format: Patch Number 117908-02 or higher
- For Solaris x86 Compressed Archive Installations: Patch 5077789
- For Windows Compressed Archive Installations: Patch 5077789
For additional details on these patches and how to apply them to your Directory Server environment, please see the README.patch file located in the Identity Synchronization for Windows download, available from:
<download_root>/patches/directory/README.patch
For the latest information about patches that may be required to install Directory Server 5 2004Q2 on Solaris, refer to the Sun Java System Directory Server 5 2004Q2 Installation and Tuning Guide and the Sun Java System Directory Server 5 2004Q2 Release Notes, which can be found at the following web site:
- Sun Java System Message Queue (formerly Sun ONE Message Queue)
version 3.5 SP1 Enterprise Edition.
Installation Credentials
To install Identity Synchronization for Windows, you must provide credentials for the following:
- Configuration directory
- Directory Server being synchronized
- Active Directory (See Installing Core for more information.)
In addition, you must have the following privileges to install Identity Synchronization for Windows:
Installation OverviewFigure 2-1 illustrates the process for installing the product for a single-host deployment.
Figure 2-1 Installing in a Single-Host Deployment
Some components must be installed in a particular order, so be sure to read all installation instructions carefully.
Identity Synchronization for Windows provides a “To Do” list, which is displayed throughout the installation and configuration process. This information panel lists all of the steps you must follow to successfully install and configure the product.
Figure 2-2 Identity Synchronization for Windows To Do List
As you go through the installation and configuration process, the program greys-out all completed steps in the list (as you can see in Figure 2-2).
The rest of this section provides an overview of the installation and configuration process, and is organized as follows:
Installing Core
When you install Core, you will be installing the following components:
- Console: Provides a centralized location for performing all of the product’s component configuration and administration tasks
- Central logger: Centralizes all audit and error logging information in a central location
- System manager: Delivers configuration updates to connectors dynamically and maintains the status of each connector
Note
Instructions for installing Core are provided in Chapter 3, "Installing Core."
Configuring the Product
After installing Core, you use the Console to initially configure the directory sources to be synchronized (and other characteristics of the deployment) all from a centralized location.
Note
Instructions for configuring directory resources are provided in Chapter 4, "Configuring Core Resources."
Preparing the Directory Server
Directory Server Connectors support the Sun Java System Directory Server 5 2004Q2.
Before you can install Directory Server Connectors, you must prepare a Sun Java System Directory Server source for every configured Directory Server master (both preferred and secondary masters) being synchronized.
You can perform this task from the Console or from the command line using the idsync prepds subcommand.
Note
Instructions for preparing Directory Server are provided in Preparing the Directory Server.
Installing the Connectors and the Directory Server Plugin
You can install any number of connectors and Directory Server Plugins, based on how many configured directories there are in your system.
Note
The Console and the installation program both use a directory’s label to associate a connector with the directory being synchronized. Table 2-3 describes Identity Synchronization for Windows’s label-naming conventions.
Note
Instructions for installing and configuring Connectors and Directory Server Plugins are provided in Chapter 5, "Installing Connectors and Directory Server Plugins."
Synchronizing Existing Users
After installing the connectors, plugins, and subcomponents you must run the idsync resync command line utility to bootstrap deployments with existing users. This command uses administrator-specified matching rules to
- Link existing entries (For a definition of linking, see Linking Users.)
- Populate an empty directory with the contents of a remote directory
- Bulk-synchronize attribute values (including passwords) between two existing user populations where entries in both the Windows and Directory Server directories are uniquely identified and linked to each other.
Note
Instructions for synchronizing existing users in your deployment are provided in Chapter 6, "Synchronizing Existing Users."
Configuration OverviewAfter installing the product, you must configure the product deployment, which includes:
This section provides an overview of the following configuration element concepts:
Directories
A directory represents:
You can configure any number of each directory type.
Configuration Directories and Global Catalogs
Identity Synchronization for Windows uses Sun Java System Directory Server configuration directories and Active Directory global catalogs as repositories in which to fetch Directory Server or Active Directory directory topology — as well as schema information for these directories.
Synchronization Settings
You use synchronization settings to control the direction in which object creations, object deletions, password and other attribute modifications are propagated between Sun and Windows directories. Synchronization flow options are as follows:
Objectclasses
When you configure resources, you will specify which entries to synchronize based on their objectclass. Object class(es) determine which attributes will be available to synchronize for both Directory Server and Active Directory.
Identity Synchronization for Windows supports two types of objectclasses:
- Structural Objectclasses: Every entry that’s created or synchronized from the selected Directory Server must have at least one structural objectclass. Select a structural objectclass from the drop-down list. (Defaults to inetorgperson on Directory Server and User on Active Directory)
- Auxiliary Objectclasses:
- Directory Server allows you to select one or more objectclasses from the Available Auxiliary Object Classes list pane to augment the selected structural class, which provides additional attributes for synchronization.
- Active Directory is more restrictive with the auxiliary objectclass. Attributes on all valid auxiliary objectclasses for the selected structural objectclass will be available for synchronization.
Note
For detailed information about configuring objectclasses and attributes, see Chapter 4, "Configuring Core Resources."
Attributes and Attribute Mapping
Attributes hold descriptive information about a user entry. Every attribute has a label, one or more values, and follows a standard syntax for the type of information that can be stored as the attribute value(s).
Note
You can define attributes from the Console. Instructions for defining attributes are provided in Chapter 4.
Attribute Types
Identity Synchronization for Windows synchronizes significant and creation user attributes, as follows:
- Significant Attributes: Synchronized between Sun and Windows directories whenever the attributes are modified according to specified modification synchronization settings.
- Creation Attributes: Synchronized between Sun and Windows directories whenever a new user is created, according to specified object creation synchronization settings.
Mandatory creation attributes are attributes that are considered “mandatory” in order to successfully complete a creation action in the target directory. For example, Active Directory expects that both cn and samaccountname have valid values upon creation. On the Sun side, if you are configuring inetorgperson of a user objectclass, Identity Synchronization for Windows will expect cn and sn as mandatory attributes for a creation.
A creation attribute default updates the target directory creation attribute with a default value only when there is no value in the attribute propagated from the originating directory. (Creation attribute defaults can be based on other attribute values. See Parameterized Attribute Default Values.)
Parameterized Attribute Default Values
Identity Synchronization for Windows allows you to create parameterized default values for creation attributes using other creation or significant attributes.
To create a parameterized default attribute value, you embed an existing creation or significant attribute name — preceded and followed by percent symbols (%<attribute_name>%) — in an expression string. For example, homedir=/home/%uid% or cn=%givenName%. %sn%.
When you create these attribute default values:
- You can use multiple attributes in a creation expression (cn=%givenName% %sn%), but the attributes in %<attribute_name>% must have single values.
- If A=%B%, then B can have one default value only.
- You can use the backslash symbol (\) for quoting (for example, diskUsage=0\%).
- Do not use expressions that have cyclic substitution conditions (for example,
sn=%uid% and uid= %sn%.Mapping Attributes
After you define the attributes to synchronize by mapping the attribute names between the Sun and Windows systems. For example, you must map the Sun inetorgperson attribute to the Active Directory user attribute.
Note
You use attribute maps for both significant and creation attributes, and you must configure attribute maps for all “mandatory creation attributes” in each directory type.
Synchronization User Lists
You create Synchronization User Lists (SULs) to define specific users in both the Sun and Windows directories to be synchronized. These definitions enable synchronization of a flat Directory Information Tree (DIT) to a hierarchical directory tree.
The following concepts are used to define a Synchronization User List:
- Base DN (not applicable to Windows NT): Includes all users in that DN unless another SUL is more specific or unless excluded by a filter.
- Filter: Uses attributes in the user’s entry to exclude users from synchronization or to separate users with the same base DN into multiple SULs. This filter uses LDAP filter syntax.
- Creation expression (not applicable to Windows NT): Constructs the DN where new users are created, for example, cn=%cn%,ou=sales,dc=example, dc=com where %cn% is replaced with the value of cn from the existing user entry. A creation expression must end with the base DN.
An SUL includes two definitions; where each definition identifies the group of users to be synchronized in the topology terms of the directory type.
When you are preparing to create SULs, ask yourself the following questions:
- Which users will be synchronized?
- Which users are excluded from synchronization?
- Where should new users be created?
Note
See Appendix D for detailed information about creating SULs.
Migrating to Version 1 2004Q3The procedures you use to migrate from Identity Synchronization for Windows version 1.0 (or version 1.0 SP1) are similar to the procedures you would use for a first-time 1 2004Q3 installation, with a few exceptions.
Note
Migration procedures are provided in Chapter 7
Before you migrate to Identity Synchronization for Windows 1 2004Q3 you should be aware of the following:
- You must restore the Directory Server Connector state file and the Active Directory and NT Connector object cache files manually after installing the connectors. Be sure you have sufficient disk space (based on the size of the /isw-home/persist directories and subdirectories) on which to save a copy of each Active Directory and NT Connector object cache.
- You must uninstall all version 1.0 and 1.0 SP1 components.
If the version 1 2004Q3 installer finds remnants of the version 1.0 system, it may cause problems with the Identity Synchronization for Windows schema installed into Directory Server and the actual Identity Synchronization for Windows binaries installed on the machine.
Note
For more information, see What to Do if the 1.0 Uninstallation Fails.
Synchronizing Passwords with Active DirectoryThe default password policy on Windows 2000 was changed on Windows 2003 to enforce strict passwords by default.
Identity Synchronization for Windows services must occasionally create entries that do not have passwords (for example, during a resync -c from Directory Server to Active Directory). Consequently, if you have password policies enabled on Active Directory (on Windows 2000 or 2003) or on Directory Server, user creation errors can result.
Although you do not have to disable password policies on Active Directory or Directory Server, you should understand the issues associated with enforcing password policies on the different systems.
The following installation information is important if you will be synchronizing passwords with Active Directory on Windows 2003 Server Standard or Enterprise Edition:
- If you are installing on Windows, you can install the Active Directory Connector on Solaris.
Note
Active Directory Connectors will work with Active Directory on both Windows 2000 and Windows 2003 Server.
- You use the same procedures to create directory sources, global catalogs, and Synchronization User Lists for Windows 2003 Server that you used for Active Directory on Windows 2000.
- On Windows 2003 Server, the default password policy enforces strict passwords, which is not the default password policy on Windows 2000.
This rest of this section is organized as follows:
- Enforcing Password Policies: If you must enforce password policies on Windows or on Directory Server, read the information provided in this section to understand how password policies can affect synchronization results between Active Directory and Directory Server.
- Example Password Policies: This section provides password policy examples for several different scenarios.
Enforcing Password Policies
This section explains how the password policies for Active Directory on Windows 2003 Server, Windows 2000, and Sun Java System Directory Server 5 2004Q2 can affect synchronization results.
The information is organized as follows:
Overview
If you create users on Active Directory (or Directory Server) that meet the required password policies for that system, the users may be created and synchronized properly between the two systems. If you have password policies enabled on both systems, the passwords must meet the policies of both systems or the synchronized user creations will fail.
- If you enable the password policy features on Active Directory, you should enable a similarly configured or matched password policy on Directory Server.
- If you cannot create a consistent password policy on both Active Directory and Directory Server, you should enable password policies on the side that you consider the authoritative source for passwords and user creations. However, there are some cases in which user creations will not work as expected because of certain password policy configurations.
Important Notes
The following sections provide important information about password policies:
Directory Server Password Policies
If you create users in Active Directory with passwords that violate the Directory Server password policy, those users will be created and synchronized in Directory Server, but the entries will be created without a password. The password will not be set until the new user logs into Directory Server, which triggers on-demand password synchronization. At this time the login will fail because the password violates the Directory Server password policy.
There are several ways to recover from this situation:
You may want to review whether the password policy set on Active Directory and on Directory Server are equivalent (or as similar as possible).
Active Directory Password Policies
If you create users on Active Directory that do not match the Active Directory password policy, those users will be created on Directory Server.
- Active Directory actually creates users “temporarily” and then deletes the entries if the password does not meet the password policy requirements. Consequently, the Active Directory Connector sees this temporary ADD and creates users on the Directory Server side. The users will not have a password in Directory Server, so no one will be able to log in as the user. In addition, these entries will not be linked to a valid entry in Active Directory. If deletions are synchronized from Active Directory to Directory Server, then the temporarily created users will be deleted automatically.
- Users are created without a password on Directory Server. Directory Server does not enforce the password policy for user creations unless the entries contain a password.
There are several ways to recover from this situation. The preferred method is to synchronize deletions from Active Directory to Directory Server. Alternatively, you can remove the user from Directory Server and then add them to Active Directory with a valid password for the Active Directory password policies. This method ensures that the users are created on Directory Server and linked properly. Users on Directory Server will have their password invalidated when they log into Active Directory for the first time and change their passwords.
- If you do not delete the user from Directory Server, and then try to add the Active Directory user again with a new password, the ADD to Directory Server will fail because the user already exists on Directory Server. The entries will not be linked together and you will have to run a idsync resync command to link the two separate accounts.
- If you run the idsync resync command, you must be sure to reset the passwords for the accounts on Active Directory that were linked to entries on Directory Server. Resetting the passwords invalidates those passwords on Directory Server, which then forces on-demand synchronization to update the Directory Server password the next time the user authenticates to Directory Server with their new Active Directory password.
Creating Accounts Without Passwords
In certain circumstances, such as resynchronization, Identity Synchronization for Windows must create accounts without passwords.
When Identity Synchronization for Windows creates entries in the Directory Server, without a password, it sets the userpassword attribute to {PSWSYNC}*INVALID*PASSWORD*. The user will not be able to log into Directory Server until you reset the password. One exception to this is when you run resync with the -i NEW_USERS or NEW_LINKED_USERS option. In this case, resync will invalidate the new user’s password triggering on-demand password synchronization the next time the user logs in.
When Identity Synchronization for Windows creates entries in the Active Directory, without a password, it sets the user’s password to a randomly chosen, strong password that meets Active Directory password policy requirements. In this case, a warning message is logged and the user will not be able to log into Active Directory until you reset the password.
The following tables describe some different scenarios you might encounter as you work with Identity Synchronization for Windows:
Use this information as a guideline to help ensure that passwords will remain synchronized. (These tables do not attempt to describe all possible configuration scenarios because system configurations differ.)
Table 2-4 How Password Policies Affect Synchronization Behavior
Scenario
Results
User Originally Created In
User Meets
Password Policy InUser Created In
Directory Server
Active Directory
Directory Server
Active Directory
Comments
Active Directory
Yes
Yes
Yes
Yes
Yes
No
Yes (see Comments)
No
Users will be created in Directory Server. However, if deletes are synchronized from Active Directory to Directory Server then this user will be deleted immediately.
See Active Directory Password Policies for more information.
No
Yes
Yes
Yes
See Important Notes for more information.
No
No
Yes (see Comments)
No
Users are created in Directory Server.
However, if deletes are synchronized from Active Directory to Directory Server then this user will be deleted immediately.See Active Directory Password Policies for more information.
Directory Server
Yes
Yes
Yes
Yes
Yes
No
Yes
No
No
Yes
No
No
No
No
No
No
Table 2-5 How Password Policies Affect Resynchronization Behavior
Scenario
Result
Resync Command
User Meets Password Policy In
Directory Server
Active Directory
resync -c -o Sun
N/A
Yes
User will be created in Active Directory but will not be able to log in.
See Creating Accounts Without Passwords for more information.
N/A
No
User will be created in Active Directory but will not be able to log in.
See Creating Accounts Without Passwords for more information.
resync -c -i NEW_USERS | NEW_LINKED_USERS
Yes
N/A
User will be created in Directory Server and their password will be set when the user first logs in.
See Creating Accounts Without Passwords for more information.
No
N/A
User will be created in Directory Server but they cannot log in because their password violates the Directory Server password policy.
See Important Notes and Creating Accounts Without Passwords for more information.
resync -c
Yes
N/A
User will be created in Directory Server but they cannot log on until a new password value is set in Active Directory or Directory Server.
See Creating Accounts Without Passwords for more information.
No
N/A
User will be created in Directory Server but they cannot log on until a new password value is set in Active Directory or Directory Server.
See Creating Accounts Without Passwords for more information.
Example Password Policies
This section describes different scenarios for Active Directory and Directory Server password policy examples using the following specifications:
Error Messages
Check the central logger audit.log file on the Core system for the following error message:
Unable to update password on DS due to password policy during on-demand synchronization:
WARNING 125 CNN100 hostname "DS Plugin (SUBC100): unable to update password of entry ’cn=John Doe,ou=people,o=sun’, reason: possible conflict with local password policy"
Note
For more information about password policies for Windows 2003, see http://www.microsoft.com/resources/documentation/WindowsServ/2003/all/deployguide/en-us/dsscc_aut_xbby.asp
For more information about password policies for Directory Server 5 2004Q2, see
Configuring Windows for SSL OperationIf you are planning to propagate password changes from Directory Server to Windows Active Directory servers you must configure each Active Directory server to use SSL and you must install the high-encryption pack.
The Identity Synchronization for Windows Active Directory Connector installer can automatically set-up SSL in the Active Directory Connector if you enable LDAP over SSL in Active Directory by automatically obtaining a certificate from a Microsoft Certificate Services Enterprise Root certificate authority as described in:
http://support.microsoft.com/default.aspx?scid=kb;en-us;q247078
However, LDAP over SSL can more easily be configured as described in this MSDN tech note:
http://support.microsoft.com/default.aspx?scid=kb;en-us;321051
In this case, if you decided to require trusted certificates for SSL communication, you must manually install the certificate in the Connector’s certificate database as described in Enabling SSL in the Active Directory Connector.
Installation and Configuration DecisionsThis section gives installation and configuration summaries and details the choices you make in deploying Identity Synchronization for Windows. Have this information available before you begin the installation process. This section contains:
Core Installation
You must provide the following information when you install Core:
- Root suffix: Specify the root suffix for the configuration directory. All configuration information is stored under this suffix.
- Administrator’s name and password: Specify credentials for the configuration Directory Server.
- Configuration password: Specify a secure password to protect sensitive configuration information.
- File system directory: Specify the location in which to install Identity Synchronization for Windows. You must install Core in the same directory as a Directory Server Administration Server.
- Unused port number: Specify an available port number for the Message Queue instance.
Core Configuration
You must provide the following information when you configure Core:
- Sun Java System Directory schema server: Specify the Directory Server data you want loaded from the configuration directory.
- User object class (for Directory Server only): Specify the user object class that will be used to determine user types. Identity Synchronization for Windows derives a list of attributes (including password attributes) based on this object class. This list is populated from the schema.
- Synchronized Attributes: Specify user entry attributes to be synchronized between the Directory Server and the Windows environment.
- Modifications, Creations, and Deletions flow: Specify how you want modifications, creations, and deletions to be propagated between the Sun and Windows systems. Your options are:
- Global Catalogs: Specify global catalogs (repositories for Active Directory topological and schema information).
- Active Directory schema controller: Specify the Fully Qualified Domain Name (FQDN) of the Active Directory schema source to be retrieved from the Windows global catalog.
- Configuration Directory: Specify the Directory Server storing the Identity Synchronization for Windows configuration.
- Active Directory Source: Specify the sources used to synchronize Active Directory domains.
- Windows NT Primary Domain Controller: Specify the Windows NT domains to be synchronized and the name of the Primary Domain Controller for each domain.
- Synchronization User Lists: Use LDAP DIT and filter information to specify the users to be synchronized on Directory Server, Active Directory, and NT.
- Sun Java System Directory Servers: Specify Directory Server instances that store users to be synchronized.
Connector and Directory Server Plugin Installation
You must provide the following information when you install the connectors and the Directory Server Plugin:
- Configuration Directory Host and Port: Specify the configuration directory host and port for the Directory Server instance on which Identity Synchronization for Windows configuration information will be stored.
- Root suffix: Specify the root suffix for the configuration directory. Use the root suffix specified during Core installation.
- Administrator’s name and password: Specify credentials for the configuration Directory Server.
- Configuration password: Specify a secure password to protect sensitive configuration information.
- File system directory: Specify the location in which to install Identity Synchronization for Windows. All components installed on the same machine must have the same installation path.
- Directory sources: Specify the directory source for which you want to install the connector or plugin.
When you are installing Directory Server and Windows NT Connectors, you must specify an unused port.
When you are installing the Directory Server Connector and Plugin, you must specify the host, port, and credentials for the Directory Server that corresponds to that Connector and Plugin.
Using the Command Line Utilities
Identity Synchronization for Windows enables you to perform a variety of tasks from the command line using the following utilities:
- You use the idsync script with the following subcommands to execute the Identity Synchronization for Windows command line utility:
- certinfo: Displays certificate information based on your configuration and SSL settings
- changepw: Changes the Identity Synchronization for Windows configuration password
- prepds: Prepares a Sun Java System Directory Server source for use by Identity Synchronization for Windows
- printstat: Prints the status of installed connectors, the system manager, and Message Queue
- resetconn: Resets connector states in the configuration directory to uninstalled (in cases of hardware or uninstaller failure only)
- resync: Resynchronizes and links existing users, and pre-populates directories as part of the installation process
- startsync: Starts synchronization
- stopsync: Stops synchronization
Note
See Appendix A for detailed information about these utilities.
- You the following utilities to migrate from Identity Synchronization for Windows 1.0 or 1.0 SP1 to Identity Synchronization for Windows 1 2004Q3:
- forcepwchg: Requires a password change for users who changed their passwords during the Identity Synchronization for Windows version 1.0 to version 1 2004Q3 migration process
- importcnf: Imports an exported version 1.0 configuration XML document
Note
See Chapter 7 for detailed information about these utilities.
Installation ChecklistsThese checklists are intended to aid in the installation process. Print them out and record the following information prior to installing Identity Synchronization for Windows.
Table 2-8 Connector and Directory Server Plugin Installation Checklist
Table 2-9 Linking Users Checklist
Required Information
Entry
Synchronization User Lists to be linked.
Attributes used to match equivalent users
XML configuration file
Table 2-10 Resynchronization Checklist