Active Directory synchronization

Directory Server, Version 6.1

Appendix G. Active Directory synchronization

Active Directory synchronization is a tool for synchronizing users and groups between an existing Microsoft® Active Directory and an IBM® Tivoli® Directory Server 6.1 directory. A ready-to-use Tivoli Directory Integrator solution is provided with IBM Tivoli Directory Server 6.1 that implements the necessary assembly lines. Synchronization is one-way, from Active Directory to IBM Tivoli Directory Server only.
Active Directory synchronization uses IBM Tivoli Directory Integrator for synchronizing the directories. The IBM Tivoli Directory Integrator Server is used to run the configuration, and the IBM Tivoli Directory Integrator Administration and Monitoring Console is used to start, stop, restart, and monitor execution. You must have IBM Tivoli Directory Integrator installed before Active Directory synchronization can run. You can install these components of IBM Tivoli Directory Integrator with IBM Tivoli Directory Server 6.1 using any of the following installation methods:

The InstallShield GUI
Operating system utilities on AIX®, Linux®, Solaris, or HP-UX systems
Silent installation on Windows® systems

The IBM Tivoli Directory Integrator Configuration Editor, which is used to develop assembly lines, is not included as part of IBM Tivoli Directory Server.
If you want to incorporate the Active Directory synchronization solution to your installation or create another type of solution for synchronizing directory data, purchase a copy of IBM Tivoli Directory Integrator 6.1.1, which includes all the features of IBM Tivoli Directory Integrator.
Notes:

The Active Directory synchronization feature and IBM Tivoli Directory Integrator must be on the same computer as the associated directory server instance.
The directory server instance must be an IBM Tivoli Directory Server 6.1 instance and the version of TDI must be version 6.1.1.
Active Directory synchronization synchronizes only users and groups. It does not synchronize other objects in the directory.
Active Directory synchronization does not synchronize nested organizational units (OUs).
Multiple attributes from Active Directory cannot be mapped to a single attribute in IBM Tivoli Directory Server.
Mapping of the userPassword attribute is not allowed. (User password data is not synchronized by this solution.)
Active Directory synchronization can synchronize users and groups from one or more user containers of Active Directory to a single OU of Tivoli Directory Server. However, it does not synchronize multiple user and group containers of Active Directory to multiple OUs of Tivoli Directory Server.
We can specify multiple user containers to synchronize with a single organizational unit (OU) in Tivoli Directory Server.
Note:

You can specify multiple user containers to synchronize with a single organizational unit (OU) in Tivoli Directory Server by using the semicolon (;) as a separator. (Other characters used as separators are not supported.) If you use the semicolon (;) separator, enclose the argument in quotation marks ("), as shown in the following example: "ou=SWUGroups,dc=adsync,dc=com;ou=STGGroups,dc=adsync,dc=com"
The sAMAccountName attribute from Active Directory will be used to compose the $dn attribute in Tivoli Directory Server. Because the sAMAccountName attribute is unique in a domain, there will not be conflicts when synchronizing multiple Active Directory user containers to a single Tivoli Directory Server OU.
The solution currently supports an SSL connection to Active Directory, but does not support an SSL connection to IBM Tivoli Directory Server.
If you configure or change the administrator DN or password (or both) for the directory server instance after configuring Active Directory synchronization, reconfigure Active Directory synchronization.
If the user or group container names from Active Directory are changed dynamically (while Active Directory synchronization is running), reconfigure Active Directory synchronization with the new names or Active Directory synchronization will no longer run.
If you modify IBM Tivoli Directory Server users and groups by a means other than Active Directory synchronization, Active Directory synchronization might not work correctly.
Synchronization is one-way, from Active Directory to IBM Tivoli Directory Server only.
Only user entry attributes are synchronized.
The synchronization from Active Directory to Tivoli Directory Server cannot be guaranteed if a user modifies users or groups in a Tivoli Directory Server instance externally, that is, outside the synchronization solution.
If you use a copy of IBM Tivoli Directory Integrator that you did not install with IBM Tivoli Directory Server 6.1, set the IDS_LDAP_IDI_HOME environment variable to the directory where you installed IBM Tivoli Directory Integrator. (On Windows systems, if there are spaces in this path, Active Directory synchronization will not work properly. Set the environment variable to a path with no spaces and no quotation marks, or use the short name when you specify the path. For example, if you wanted to specify the C:\Program Files\IBM\TDI\V6.1.1 directory, you could use c:\progra~1\IBM\TDI\V6.1.1 to avoid spaces in the path.)
Note:

Steps for using Active Directory synchronization

After you install IBM Tivoli Directory Server 6.1 (including IBM Tivoli Directory Integrator) and create and configure a directory server instance, use the following steps to configure and use Active Directory synchronization:

Optionally, load the sample users.ldif and groups.ldif files into the Active Directory Server. Use the documentation for Active Directory Server.
Configure Active Directory synchronization using the IBM Tivoli Directory Server Configuration Tool or the idsadscfg command. This generates the adsync_private.prop and adsync_public.prop files. See the IBM Tivoli Directory Server Version 6.1 Installation and Configuration Guide for information.
Modify the adsync_public.prop file to customize optional attributes and SSL parameters, if needed. See Files used by Active Directory synchronization for information. If you are using SSL, see Configuring Active Directory synchronization to use an SSL connection to Active Directory for information.
Start Active Directory synchronization, using the idsadsrun command. You are asked if you want to fully synchronize, followed by real time synchronization, or only start real time synchronization. See Running Active Directory synchronization for information.
Changes made to the Active Directory entries will be read by the Active Directory synchronization, which listens for changes.
Active Directory synchronization will synchronize any changes to the IBM Tivoli Directory Server directory. The IBM Tivoli Directory Integrator Administration and Monitoring Console can be used for further administration and monitoring.

Note:

We can use either the Configuration Tool or the idsadscfg command to configure Active Directory synchronization.
For information about configuring Active Directory synchronization with the Configuration Tool, see the IBM Tivoli Directory Server Version 6.1 Installation and Configuration Guide.
For information about configuring Active Directory synchronization with the idsadscfg command, see the IBM Tivoli Directory Server Version 6.1 Command Reference.

Files used by Active Directory synchronization

The following files are used by Active Directory synchronization:
adsync.xml

The adsync.xml file is a configuration file. It provides the pre-configured assembly lines and connectors needed to perform the synchronization of Active Directory with IBM Tivoli Directory Server. It was originally created using the IBM Tivoli Directory Integrator Configuration Editor utility. There is only one adsync.xml file on a computer. This file cannot be changed. For customization, each IBM Tivoli Directory Server 6.1 directory server instance is configured to create properties files that define how the Active Directory synchronization works for the specific directory server instance.

Properties files
Two property files (adsync_private.prop and adsync_public.prop) are updated when a directory server instance is configured for Active Directory synchronization. The adsync.xml file contains a reference to these external properties files.
The adsync_private.prop properties file is encrypted and the property values in this file can be modified only through the Configuration Tool or the idsadscfg command.
Active Directory synchronization uses the following attributes as mandatory attributes to synchronize the IBM Tivoli Directory Server user entries:

$dn attribute (created from sAMAccountName
cn
sn
uid
objectClass

The following is an example of an adsync_private.prop file:
Adhost1.AdGroupContainer:ou=SWUGroups,dc=adsynctest,dc=com
Adhost1.AdLdapLoginName:cn=administrator,cn=users,dc=adsynctest,dc=com
Adhost1.AdLdapPwd:dd06proxy
Adhost1.AdLdapSrchBase:dc=adsynctest,dc=com
Adhost1.AdLdapUrl:ldap://localhost:389
Adhost1.AdLdapUserContainer:ou=sales,dc=adsynctest,dc=com
Adhost1.IbmLdapGroupContainer:ou=groups,o=sample
Adhost1.IbmLdapUserContainer:ou=Austin,o=sample
IbmLdapLoginName:cn=root
IbmLdapPwd:sec001ret
IbmLdapSrchBase:ou=austin,o=sample
IbmLdapSuffix:o=sample
IbmLdapUrl:ldap://localhost:2389
The remaining attributes are optional and we can change these attributes (and the mapping) in the <instance_home>/tdisoldir/adsync_public.prop file.
The adsync_public.prop file is an ASCII text file. It contains the following properties, which we can modify:
Table 32. Properties in the adsync_public.prop fil

Property Description Example

AdDc1.AdSSL A value of true indicates that SSL has been configured and will be used for the connection to Active Directory.
A value of false indicates that the connection will not be over an SSL session.
If the value is set to true, follow the instructions in Configuring Active Directory synchronization to use an SSL connection to Active Directory to configure a key file on the IBM Tivoli Directory Integrator server before running the configuration.
true
TdsOptionalAttributes List of attributes, separated by semicolon (;) characters, with optional syntax [attribute:(colon)attribute].
These attributes signify that each attribute name from Active Directory can be stored in IBM Tivoli Directory Integrator (Initial Work Entry) with a different name, which can further be used to map the attribute to a different attribute in IBM Tivoli Directory Server.
The attributes are case sensitive.
Multiple attributes cannot be mapped to a single IBM Tivoli Directory Server Attribute.
The userPassword attribute cannot be mapped.
otherTelephone:telephoneNumber signifies that attribute otherTelephone from Active Directory is mapped to the corresponding attribute telephoneNumber in the IBM Tivoli Directory Server entry.
LogLevel Active Directory solution uses the LogLevel parameter to log the adsync configuration and execution details. The following log levels can be specified:

DEBUG
INFO
WARN
ERROR
FATAL

The following is an example of an adsync_public.prop file:
Adhost1.OptionalAttributes:mail;displayName:cn;l:city;postalCode;init
ials:initials;givenName:givenName;streetAddress:street;st:st;departme
nt:departmentNumber;telephoneNumber:telephoneNumber;title:title;physi
calDeliveryOfficeName:roomNumber;otherTelephone:telephoneNumber;descr
iption:descriptionibmLdaphost1.OptionalAttributes:mail; cn; city:l;po
stalCode;initials;givenName;street;st;departmentNumber;telephoneNumbe
r;title;roomNumber;descriptionAdhost1.AdLdapSSL: false
adsync_cfg.xml

This file is used during configuration, either through the Configuration Tool or the idsadscfg command. This file contains an AssemblyLine that takes the configured parameters and creates the adsync_private.prop and adsync_public.prop properties files.

groups.ldif (sample file)
This file contains the sample groups to be added to the Active Directory setup. This is the sample data used to synchronize between Active Directory and IBM Tivoli Directory Server. Do not use this file as it is. It is modified during configuration with the user and group container and domain information you specify.
An example groups.ldif file is:
CN=SWUGroup1,OU=SWUGroups,dc=adsynctest,dc=com
objectClass=top
objectClass=group
cn=SWUGroup1
member=CN=lwood,ou=sales,dc=adsynctest,dc=com
member=CN=jdixon,ou=sales,dc=adsynctest,dc=com
member=CN=jcarroll,ou=sales,dc=adsynctest,dc=com
member=CN=twatson,ou=sales,dc=adsynctest,dc=com
member=CN=jsanchez,ou=sales,dc=adsynctest,dc=com
sAMAccountName=SWUGroup1
groupType=-2147483646

CN=SWUGroup2,OU=SWUGroups,dc=adsynctest,dc=com
objectClass=top
objectClass=group
cn=SWUGroup2
member=CN=amason,ou=sales,dc=adsynctest,dc=com
member=CN=swilson,ou=sales,dc=adsynctest,dc=com
member=CN=Elizabeth Brown,ou=sales,dc=adsynctest,dc=com
sAMAccountName=SWUGroup2
groupType=-2147483646
users.ldif (sample file)
This file contains the sample users to be added to the Active Directory setup. This is the sample data used to synchronize between Active Directory and IBM Tivoli Directory Server. Do not use this file as it is. It is modified during configuration with the user and group container and domain information you specify.
An example users.ldif file is:
CN=lwood,ou=sales,dc=adsynctest,dc=com
cn=lwood
displayName=LORI H. WOOD
givenName=LORI
initials=H
objectClass=top
objectClass=person
objectClass=organizationalPerson
objectClass=user
physicalDeliveryOfficeName=8B001
name=lwood
sAMAccountName=lwood
sn=WOOD
userAccountControl=544
userPrincipalName=lwood@xyz.com

CN=pburns,ou=sales,dc=adsynctest,dc=com
cn=pburns
displayName=PATRICK BURNS
givenName=PATRICK
objectClass=top
objectClass=person
objectClass=organizationalPerson
objectClass=user
name=pburns
sAMAccountName=pburns
sn=BURNS
userAccountControl=544
userPrincipalName=pburns@xyz.com
adsync.log

Synchronization details (idsadsrun execution) are logged in adsync.log file which resides at the following location: <TDS instance home>/tdisoldir/logs folder.
Details about logging can be configured using the LogLevel parameter in the <TDS instance home>/tdisoldir/adsync_public.prop file. Default value of the LogLevel parameter is INFO which can be changed to DEBUG to get the debug logs. For further details refer to TDI Logging.
Running Active Directory synchronization

Use the idsadsrun command to run Active Directory synchronization after it is configured. For information about running Active Directory synchronization with the idsadsrun command, see the IBM Tivoli Directory Server Version 6.1 Command Reference.
Note:

If there are errors in the parameters specified for Active Directory, these errors will found at runtime and not during configuration, If errors are reported during runtime in the Active Directory parameters, reconfigure the Active Directory parameters correctly using the Configuration Tool (in the Active Directory synchronization: Active Directory details window) or the idsadscfg command.

Configuring Active Directory synchronization to use an SSL connection to Active Directory

We can use an SSL connection to Active Directory Server. (However, you cannot use an SSL connection to IBM Tivoli Directory Server.) To set up Active Directory synchronization to work with an SSL connection to Active Directory:
Configure Active Directory synchronization to use the appropriate port number. Additionally:

If you are using the Configuration Tool to configure, be sure to select the Use SSL connection to Active directory check box in the Active Directory synchronization: Instance Details window and to provide the correct port number in the Host port field in the Active Directory synchronization: Active Directory details window. (Do they need to cfg the port number??)
If you are using the idsadscfg command to configure, be sure to use the -Z flag.

Configure Active Directory to SSL using the self certificate as follows:

Install Certificate Services on the Windows 2003 Server and an Enterprise Certificate Authority in the Active Directory Domain. Be sure that you install an Enterprise Certificate Authority. (Windows only???)
Start the Certificate Server Service. This creates a virtual directory in Internet Information Service (IIS) that enables you to distribute certificates.
Create a Security (Group) Policy to direct Domain Controllers to get an SSL certificate from the Certificate Authority (CA).
Open the Active Directory Users and Computers Administrative tool.
Under the domain, right-click Domain Controllers. Select Properties.
On the Group Policy tab, click to edit the Default Domain Controllers Policy.
Go to Computer Configuration -> Windows Settings -> Security Settings -> Public Key Policies.
Right-click Automatic Certificate Request Settings.
Select New.
Select Automatic Certificate Request.
Run the wizard. Select the Certificate Template for a Domain Controller.
Select your Enterprise Certificate Authority as the CA. Selecting a third-party CA works as well.
Complete the wizard.
All Domain Controllers now automatically request a certificate from the CA and support LDAP using SSL on port 636.
Retrieve the Certificate Authority Certificate to the computer on which you installed Active Directory synchronization.
Note:

You must install IIS before installing the certificate server.
Open a Web browser on the computer on which you installed Active Directory synchronization.
Go to http://<server_name>/certsrv/ (where <server_name> is the name of the Windows 2003 server). You are asked to log in.
Select the task Retrieve the CA certificate or certificate revocation list and click Next.
The next page automatically highlights the CA certificate. Click Download CA certificate.
A new download window opens. Save the file to the hard drive.
Generate a jks file and configure Active Directory synchronization as follows:
Create a certificate store using keytool. Use the keytool.exe file to create the certificate store and import the CA certificate into this store.
Note:

the keytool.exe file is located in the IBM Directory Integrator directory in the /_jvm/bin directory.
Use the following command:
_jvm\bin\keytool -import -file certnew.cer -keystore <keystore_name>.jks 
    -storepass <password> -alias <keyalias_name>
For example, assume the following values:

Keystorename = idi.jks
Password = secret Keyalias
name = AD_CA

The command with these values is as follows. (Assume that you are in the C:\Program Files\IBM\IBMDirectoryIntegrator directory.)
_jvm\bin\keytool -import -file certnew.cer -keystore idi.jks 
    -storepass secret -alias AD_CA
To verify the contents of your keystore, type the following:
_jvm\bin\keytool -list -keystore idi.jks -storepass secret
This results in the following:
Keystore type: jks
Keystore provider: SUN
Your keystore contains 1 entry:
ad_ca, Mon Nov 04 22:11:46 MST 2002, trustedCertEntry,
Certificate fingerprint (MD5): A0:2D:0E:4A:68:34:7F:A0:21:36:78:65:A7:1B:25:55
Configure Active Directory synchronization to use the keystore created in step 3, as follows:
Edit the <TDS Instance Home directory>/tdisoldir/solution.properties file to set the keystore file location, keystore file password, and keystore file type. (In the current release, only the jks type is supported.)
#server authentication
#example
javax.net.ssl.trustStore=c::\test\idi.jks
javax.net.ssl.trustStorePassword=secret
javax.net.ssl.trustStoreType=jks
#client authentication
#example
javax.net.ssl.keyStore=c:\test\idi.jks
javax.net.ssl.keyStorePassword=secret
javax.net.ssl.keyStoreType=jks
Start Active Directory synchronization using the idsadsrun command. The solution will connect to Active Directory over SSL.
[ Top of Page | Previous Page | Next Page | Contents | Index ]

Property	Description	Example
AdDc1.AdSSL	A value of true indicates that SSL has been configured and will be used for the connection to Active Directory. A value of false indicates that the connection will not be over an SSL session. If the value is set to true, follow the instructions in Configuring Active Directory synchronization to use an SSL connection to Active Directory to configure a key file on the IBM Tivoli Directory Integrator server before running the configuration.	true
TdsOptionalAttributes	List of attributes, separated by semicolon (;) characters, with optional syntax [attribute:(colon)attribute]. These attributes signify that each attribute name from Active Directory can be stored in IBM Tivoli Directory Integrator (Initial Work Entry) with a different name, which can further be used to map the attribute to a different attribute in IBM Tivoli Directory Server. The attributes are case sensitive. Multiple attributes cannot be mapped to a single IBM Tivoli Directory Server Attribute. The userPassword attribute cannot be mapped.	otherTelephone:telephoneNumber signifies that attribute otherTelephone from Active Directory is mapped to the corresponding attribute telephoneNumber in the IBM Tivoli Directory Server entry.
LogLevel	Active Directory solution uses the LogLevel parameter to log the adsync configuration and execution details. The following log levels can be specified: DEBUG INFO WARN ERROR FATAL