Previous Contents Index Next |
iPlanet Meta-Directory Configuration and Administration Guide |
Chapter 11 Configuring the Active Directory Connector
This chapter discusses configuration factors specific to the Active Directory Connector, which provides bi-directional synchronization of Active Directory user and group data into its connector view. During instance creation, the connector enables you to select from a default schema or ADSpecific schema. The default schema is based on the objectclasses of iPlanet Directory Server, whereas the ADSpecific schema represents all user and group attributes present in the Microsoft Active Directory.The topics in this chapter are:
Installing the Connector
Configuring a Participating Connector View
Configuring a Connector Instance
Restarting the Connector Instance
Implementing the Configuration
Installing the Connector
The following components must be installed before you install the connector:
iPlanet Directory Server 4.x or 5.x, as described in the Deployment Guide. Restart the server after enabling the change logs.
iPlanet Meta-Directory 5.0SP1, as described in the Deployment Guide. Make sure to select Active Directory Connector in the Components screen when you install Meta-Directory.
To install the Active Directory Server Interface (ADSI) package
Access the following URL:
Select Version 2.5 for Intel x86 (English), then download ads.exe.
- http://www.microsoft.com/ntserver/nts/downloads/other/ADSI25/
default.asp
To add a connector view instance
You can set configuration parameters during instance creation or from the configuration file. The configuration file contains extra parameters for setting the schema and modes.
To set configuration parameters during instance creation
From the iPlanet Console 5.0 window, right-click on Server Group. A context menu appears.
Select Create Instance Of, then select Meta-Directory Active Directory Connector. The New Instance Creation dialog box appears.
Provide input for the data fields. The dialog box for the Active Directory Connector contains additional fields. See Table 11-1 for a description of these fields.
Table 11-1    Dialog Box Parameters
Dialog Box Parameter
Definition
Domain
Domain Controller User Name
Specifies the user name for the directory connector where Active Directory exists.
Domain Controller Password
Specifies the password associated with the domain controller user name.
Top Level Synch DN
Specifies the top level DN where Active Directory Connector synchronization occurs.
Be advised that you should enter input in this field accurately. If the top level in Active Directory (from where users/groups are being synchronized) is under the 'Users' node in the Management Console (MMC), the entry should be:
If the user/group entries in Active Directory are to be added under a new organizational unit, such as newou, the entry should be:
All other users and groups under the DN mentioned above will be synchronized.
Host Name
Specifies the host address of the domain controller where the Active Directory exists.
Schema
Enables switching from the default schema to the ADSpecific schema. The ADSpecific schema provides additional attributes and object classes that are not ordinarily available in the default user/group object classes in the Directory Server, shown in Table 11-2 and Table 11-3.
Every attribute name or object class of Active Directory for ADSpecific is prepended with mdsAD (ex: mdsADTelephoneNumber).
Log Level
Specifies the log level for the task script and accessor utility. Values are as follows:
0 - None
1 - Minimum
2 - Verbose
3 - Very verboseAfter you set the log level from the dialog box, you cannot change it from there. You must use the configuration file to change the log level.
To set configuration parameters from the configuration file
Locate the adc.ini configuration file in the following directory:
- NetsiteRoot/adc-ViewName/config/adc.ini
Provide values for the file parameters. The following table provides definitions for the configuration file parameters.
- Netsite_Root is the installed path for Meta-Directory. The default is c:\iPlanet\Servers. The ViewName is the name you provided in the New Instance Creation dialog box.
Configuration File Parameter
Definition
NTLMdomain\user Specifies the pre-Windows 2000 abbreviated name of the domain to be synchronized. Example:
username Specifies the Windows 2000 account name that the directory connector uses to authenticate Active Directory.
password Specifies the password associated with the domain controller user name.
adtopleveldn Specifies the top level DN where Active Directory Connector synchronization occurs.
utctopleveldn Specifies the View Base DN as entered in the New Instance Creation dialog box.
domain dc Specifies the host address of the domain controller where the Active Directory exists.
schema Enables switching from the default schema to the ADSpecific schema. The ADSpecific schema provides additional attributes and object classes that are not ordinarily available in the default user/group object classes in the Directory Server, shown in Table 11-2 and Table 11-3.
Every attribute name or object class of Active Directory for ADSpecific is prepended with mdsAD (ex: mdsADTelephoneNumber).
logginglevel Specifies the log level for the task script and accessor utility. Values are as follows:
0 - None
1 - Minimum
2 - Verbose
3 - Very verboseAfter you set the log level from the dialog box, you cannot change it from there. You must use the configuration file to change the log level.
finddeletedfreq Specifies the frequency of synchronization cycles that search for deleted entries. For instance, a value of 5 would search for deleted entries on the fifth cycle.
This parameter is used in conjunction with the Schedule window, described on page 143.
loggingsize Specifies the maximum size of the accessor log file in megabytes (Mb). The default is 4096 Mb.
perllogfilesize Specifies the maximum size of the Perl log file in megabytes (Mb). The default is 4096 Mb.
searchattrs Specifies a list of comma-separated Active Directory attributes. The list determines which attributes Active Directory retrieves. If you do not provide a list (blank), all attributes are selected.
disallowattribs This is a comma-separated list of attributes that you do not wish to be flown to the Active Directory. This is effective only when the schema is set to ADSpecific mode at instance-creation time, or edited in adc.ini. You can add to this list any other attributes that need to be eliminated while writing into the active directory. For example:
dissalwattribs=mdscvlinktype,mdsentityowner, mdslintomv,mdsvmembership
To add the instance as a participating view
Right-click the Participating Views object. A context menu appears.
Select Add Participating View. The Select View dialog box appears.
Select the connector view you want to add or participate in a join/synchronization with the meta view.
Click OK. The view is added to the iPlanet Meta-Directory configuration tree.
To provide authorization
Provide authorization of created users for data server access. See "Setting Access Permissions" for the procedure.
Configuring a Participating Connector View
If you have installed the join engine, you can configure a participating view for the Active Directory connector. Refer to the procedures in Chapter 6 "Views in Meta-Directory."
Creating Users
The following procedures apply only to the meta view. If you have installed the join engine and want to create new entries, you should create them from the meta view. The connector view only reflects the contents of the external data source or meta view.
To create an Active Directory user in the meta view
Click on the Contents of the Active Directory meta view.
You can also create Active Directory users in the meta view by using an LDIF file format within any LDAP client. The LDIF format should be similar to the structures of user entries and group entries, discussed on page 206 and page 208.
Provide input in the required fields. A default user ID is generated when you enter the first and last names. Make sure that the User ID field is alphanumeric and does not contain any of the following characters:
- From the menu bar, select Object > New > User. The Create New User dialog box appears.
Click OK. The user name appears in the right pane of the Meta-Directory console.
- - ~ ! @ # $ % ^ & * ( ) _ + | \ : " , . < > / ?
To modify an Active Directory user in the meta view
Click on the Contents of the Active Directory meta view.
Double-click on the Active Directory user you want to modify. The Edit Entry dialog box appears.
Configuring Connector Rules
You can configure the following types of rules for the Active Directory connector:
Attribute Flow
To configure connector rules, see "Attribute Flow Rules", "Default Attribute Value Rules", and "Filter Rules".
- The connector uses attribute flow rules to specify which external data source attributes are mapped to which connector view attributes and vice versa. Active Directory provides the following preset configurations:
Minimal Attribute Set for Default Schema, which is the minimum set of attributes necessary to flow data
Complete Attribute Set for Default Schema, which represents the complete Directory Server schema
Default Values
- Attribute flow is functional only for the default schema configurations. If you create a new configuration, you cannot apply it to the connector instance running in ADSpecific mode, as documented in 1b in the next section.
- If you select one of the configurations, remove a few attributes, then save the configuration, you cannot revert to the original list of attributes by clicking Insert Defaults. Clicking this button populates the list box at the bottom of the window with default mappings that you can delete or change.
Filters
- The connector applies preconfigured attribute rules to an entry in the external data source if no value is assigned to the same attribute in its corresponding entry in the connector view, or vice versa. A default attribute rule may also be configured.
- Default values are functional only for the default schema configurations. If you create a new configuration, you cannot apply it to the connector instance running in ADSpecific mode as documented in 1b in the next section.
- The connector uses filtering rules to selectively exclude entries from the synchronization process.
Configuring a Connector Instance
Consider the following procedure an extension of the comprehensive configuration procedures in "Configuring a Universal Connector Instance". You need to perform the following product-specific procedure for every Active Directory Connector.
To automatically configure attribute flow, proceed to Step a below. To manually configure, go to Step 2.
Select the connector instance for which you want to provide attributes. The General window appears, as shown in .
Optional: Manually configure the attribute flow by doing the following:From the drop-down lists, select the desired attribute flow, filter, and default value configurations. The values that appear are derived from the rules you configured for the connector in the section "Configure Connector Rules".
You can remove attributes from the complete set, if desired, before saving the configuration. The minimum configuration consists of the following attributes:
Select the operation you want to perform.
If you chose the default schema while creating an Active Directory Connector instance, and if you chose the minimal attribute set for attribute flow configuration, the following attributes should synchronize from Active Directory to the connector view:
- See Table 11-2 and Table 11-3 for the complete list of external attributes.
- uid
cn
sn
objectclass
- All 37 default attributes should synchronize from the connector view to Active Directory.
Click Save, then go to step 3.
Select the Active Directory Connector, then select the Attribute Flow tab, as shown in .
Configure the remaining windows for the connector instance. Begin with "To configure the schedule from and to connector views".Click New and enter a new configuration name, then click OK.
Click Insert. The Insert Attribute Mappings dialog box appears. For both mapping types (locally owned objects and connector view-owned objects), map each attribute to itself for both flow directions (to connector view and from connector view).
Click Save, select View from the menu bar, then select Refresh.
- For example, the figure below shows the description attribute being mapped to itself for a flow direction to the connector view. This would also have to be repeated for a flow direction from the connector view.
Select the desired Active Directory Connector instance. The General window appears, as shown in .
From the Attribute Flow Configuration drop-down list, select the attribute flow configuration name you created (Step b). The name becomes available in the list after refreshing (Step d).
Select the desired filters and default values from the drop-down lists.
Select the operation you want to perform and click Save.
Restarting the Connector Instance
You must restart the connector instance to activate your configuration. Both instance-specific and shared configurations will not become effective for a given instance until you have restarted the instance. If the entries you are saving preexist in an Active Directory connector view, see page 206 for advisory information.
Stop the connector by right-clicking on the connector instance. A context menu appears.
Click Yes to the prompt. A message appears stating that the stop command has been issued to the component.
Start the connector by right-clicking on the connector instance. A context menu appears.
Select Start Server. A message appears stating that the start command has been issued to the component.
Note To start the connector, you must be a member of the Administrators group on the primary domain controller.
Implementing the Configuration
After you start the join engine and enable the connector view, your data can flow to the meta view. The following sections provide procedures for doing these tasks.
Starting the Join Engine
Before you start the join engine, ensure that you have already enabled the changelog in the Directory Server configuration.
Select the join-engine object from the navigation tree and right-click. A context menu appears.
You can also start the server from the iPlanet Console. To do this, select the Join Engine object and right-click. Select Start Server from the context menu.Select Start Server. A message appears stating that the server has been started.
From the iPlanet Meta-Directory window, click on the Status tab.
Click on the Join Engine object. The Operations tab window appears.
Select the participating view you want to enable.
Select Enable from the Operation list menu, then click Submit Request.
Select Refresh from the Operation List Window, then select either Meta View or Connector View from the Traverse menu list.
- This option disables the Traverse drop-down menu. You can only enable the participating view if the configuration for setting up the view is valid. Any error in the configuration automatically changes the view to a disable status.
Refreshing the View
You can optionally refresh the view if you want to observe updates immediately and bypass the regularly scheduled refresh synchronization. Note that after any type of refresh, you might see a "None" group in the meta view Contents or connector view Contents, particularly with non Primary Domain Controller systems. "None" is a valid group in Windows NT.
From the iPlanet Meta-Directory window, click on the Status tab.
Click on the NT Domain connector instance object. The Operations tab window appears. The only operation available is Refresh.
In the "Updates to the" drop-down list, select either External Directory or Connector.
Click Start. The Modify Task Status dialog box appears. If you are refreshing the connector view, the following version of the box appears:
- If you are refreshing the external directory, the following version of the box appears:
- You must select a filter for the second and third options. Only filters configured for the "NoSubtreesExcept" option are displayed when you click Select Filter, not filters configured for the "AllSubtreesExcept" option.
Monitoring the Connector
The Active Directory Connector provides logs at the following locations that enable you to monitor connector status.
For example, a Perl log file entry might appear as follows:
You should ignore the churchfield.com domain name if it appears in the UTC log.
Errors you may encounter in the Accessor Utility Log are as follows:
For other errors, refer to the following Microsoft Product Support Services site:
http://support.microsoft.com/support/kb/articles/Q242/0/76.asp
Data Flow for User and Group Entries
Entries in the Active Directory connector view must adhere to certain conditions to flow from the connector view into the Active Directory. Note the following restrictions and advisory information:
You should use the default in ADSpecific mode.
When setting up the join engine, you need to ensure that user and group entries meet the required criteria for Active Directory Connector views. The following sections discuss the requirements and list the available external attributes read from Active Directory for both user and group entries.To prevent duplicate user IDs from occurring in the same connector view, the meta view connector views must be separate entities. A connector view should not be nested as a subtree of another connector view. That is, the connector view should be a flat tree that does not contain any subentries.
Entries that preexist in an Active Directory connector view will not flow to the meta view after the connector starts. To flow these entries, the Active Directory connector view must be an enabled participating connector view in the join engine. Refreshing the meta view operation from the join engine will trigger the preexisting entries from the Active Directory connector view to flow to the meta view.
If you create users or groups from the console with the default objectclasses in ADSpecific mode, the users or groups propagate to Active Directory. If you synch these entries back to a different connector view, the entries are created on the new connector view with mdsADUser or mdsADGroup objectclasses. Sphere icons appear, rather than the standard person or group icons.
User Entries
You can create Active Directory users in the connector view with any LDAP client by adhering to the attribute conventions shown in the following structure for the default schema:dn: uid=userid, cvroot_dn
uid: userid
cn: user_full_name
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: mdsADuser
mdAdsn: user_second_nameFor the ADSpecific schema, the structure would be as follows:
dn: cm=user_cn,cvroot_dn
objectclass: mdsADtop
objectclass: mdsADperson
objectclass: mdsADorganizationalPerson
objectclass: mdsADuserNote the following restrictions:
The userid cannot contain the following characters:
Table 11-2 shows the available external attributes for user entries in default schema mode. Refer to your Active Directory documentation for more information about these attributes.
The user name cannot consist solely of periods or spaces.
- " / \ [ ] : ; | = , + - * ? < >
Group Entries
The group entries in the connector view contain the list of member DNs. The connector view applies static group membership.You can create NT groups in the connector view with any LDAP client by adhering to the attribute conventions shown in the following structure for the default schema:
dn: cn=groupname, cvroot_dn
objectclass: top
objectclass: groupOfNamesFor the ADSpecific schema, the structure would be as follows:
dn: cn=groupname, cvroot_dn
objectclass: mdsADtop
objectclass: mdsADgroupOfNamesTable 11-3 shows the available external attributes for group entries. Refer to your Active Directory documentation for more information about these attributes.
Table 11-3    Attributes for Group Entries
cn
member
description
objectclass
distinguishedname
samaccountname
grouptype
Configuration Example
The following ADSpecific schema example is intended as a quick reference you can use as a checklist. For complete configuration information, refer back to the earlier portions of this chapter.
Ensure that iPlanet Directory Server 4.x or 5.x, and iPlanet Meta-Directory 5.0SP1 are already installed.
Create a connector view instance.
- During instance creation:
From the iPlanet Console 5.0 window, right-click on Server Group. A context menu appears.
Select Create Instance Of, then select Meta-Directory Active Directory Connector. The New Instance Creation dialog box appears.
Provide input for the data fields. For View Name, use Active. For View ID, use CV1. For View Base DN, use o=CV1. For Schema, use default. For the remaining fields, see Table 11-1 on page 193.
- From the configuration file:
Locate the adc.ini configuration file in the following directory:
Add the instance as a participating view.Provide values for the file parameters. Use default parameters and values.
- NetsiteRoot/adc-ViewName/config/adc.ini
Provide authorization. See "Setting Access Permissions".
Configure attribute flow.
Click on the Active Directory connector. The Attribute Flow tab window appears.
Configure default attribute rules.Select the Minimal Attribute Set for Default Schema from the list of configurations. Note that the manager attribute does not appear in any of the three configuration choices. The Active Directory checks this attribute for referential integrity, and an arbitrary value causes the Active Directory connector to fail.
In the Mapping Type drop-down list, select Mappings for Connector View Owned objects.
Click Insert. The Insert Attribute Mappings dialog box appears. This displays a list of all available attributes from both the external data source and the Connector View.
For Mapping Type, select Mapping for Connector View Owned objects. For Flow Direction, select From Connector View. For Connector View Objectclass, select All Attributes.
For External Attribute, select homephone. For Connector View Attribute, select telephonenumber.
Click Insert. The mapping for your configuration appears at the bottom of the Attribute Flow window.
Click Close, and then click Save from the Attribute Flow window.
Click on the Default Values tab. The Default Values window appears.
Configure filters.In the Name field, type in ActiveDefault. The name is echoed in the Configurations list box.
In the Attribute Destination drop-down list, select External Directory.
Click Add. Blank fields appear below the Attribute and Default Value fields.
Click within the blank Attribute field. A drop-down list appears. Select givenname from the list.
Double-click within the blank Default Value field and type in surname.
Click on the Filters tab. The Filters window appears.
Click New. The Filter Name dialog box appears.
Type in ActiveExclude and click OK. The new name appears in the Filter Name list box.
Provide a list of subtrees to exclude by selecting All Subtrees Except, then clicking Add. The Sub-tree DN dialog box appears.
Click Save.Specify a subtree to exclude, such as o=siroe,c=us, then click OK. The subtree appears in the list box.
Filter back entries from the excluded subtrees using entry-level filters. Select the subtree you just created, select All Entries Except, then click Add. The Entry RDN dialog box appears.
- With this filter, entries in all subtrees that are not specifically excluded are included, no matter how you set the associated entry-level filters.
Specify an entry you want to include, such as cn=Fred Scofflaw, then click OK. The included entry appears in the list box.
- The entry-level filters you apply affect only the entries found in the list of subtrees to include. The entries you specify here will filter through; all others are excluded.
From the menubar, select View > Refresh.
Configure a Connector Instance
Select the adc-Active connector instance. The General window appears.
Select the following from the drop-down lists:
For Configuration, select Minimal Attribute Set for Default Schema.
For Operation, select "Only receive updates from the Connector View."For Filter Configuration, select ActiveExclude.
For Default Values Configuration, select ActiveDefault.
Click Save. Leave the current values for fields in the Schedule, Log, and Attributes windows.
Restart the Connector Instance
Stop the connector by right-clicking on adc-Active. A context menu appears.
Click Yes to the prompt. A message appears stating that the stop command has been issued to the component.
Start the connector by right-clicking on adc-Active. A context menu appears.
Select Start Server. A message appears stating that the start command has been issued to the component.
Previous Contents Index Next
Copyright © 2002 Sun Microsystems, Inc. All rights reserved.
Last Updated April 08, 2002