Chapter 7 Configuring the Active Directory Connector

Chapter 7
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 to 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 Sun ONE Directory Server, whereas the ADSpecific schema represents all user and group attributes present in the Microsoft Active Directory.

The topics in this chapter are:

The following components must be installed before you configure the connector:

Sun ONE Directory Server 5.2, as described in the Directory Server Installation and Deployment Guides. Restart the server after enabling the retro-changelog plug-in.

Sun ONE Meta-Directory 5.1.1, as described in the Meta-Directory Installation and Deployment Guides. Ensure that you select ‘Active Directory Connector’ in the Components screen when you install Meta-Directory.

Creating a Active Directory 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 Sun ONE Console window, right-click Server Group.

Choose Create Instance Of > Active Directory Connector.

The ‘New Instance Creation’ dialog box displays.

Enter appropriate data in the fields. See table for a description of these fields.

Table 7-1 Dialog Box options
Field	Do This
Domain	Specifies the domain where Active Directory exists.
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: cn=Users,dc=madisonparc,dc=com If the user/group entries in Active Directory are to be added under a new organizational unit, such as newou, the entry should be: ou=newou,dc=myhost,dc=com 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 7-4 and Table 7-5. Every attribute name or object class of Active Directory for ADSpecific is prepended with mdsAD (for example, 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 verbose After 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:

Netsite_Root/adc-ViewName/config/adc.ini

Netsite_Root is the installed path for Meta-Directory. The default is c:\Sun\Servers. The ViewName is the name you provided in the ‘New Instance Creation’ dialog box.

Provide values for the file parameters. The following table provides definitions for the configuration file parameters:

Table 7-2 File Parameters definition
Configuration File Parameter	Definition
NTLMdomain\user	Specifies the pre-Windows 2000 abbreviated name of the domain to be synchronized. For example: restaurants instead of restaurants.madisonparc.com
username	Specifies the Windows 2000 account name that the directory connector uses to authenticate Active Directory.
password1	It is associated with the domain controller’s user name. Do not modify this parameter.
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	This parameter is not currently used.
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 7-4 and Table 7-5. Every attribute name or object class of Active Directory for ADSpecific is prepended with mdsAD (for example, 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 verbose After 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 2	Specifies that every nth scheduled synchronization, the connector should run in the ‘Find Delete’ mode. This is done to process the deleted entries (since incremental mode does not handle deletes). For instance, when finddeletedfreq = 2, the connector will run in the ‘Find Delete’ mode, at every 2nd scheduled sync. This parameter is used in conjunction with the Schedule window, described in the "To configure the schedule from and to Connector Views" section.
loggingsize	Specifies the maximum size of the accessor log file in kilobytes (KB). The default value is 4096 KB.
perllogfilesize	Specifies the maximum size of the Perl log file in kilobytes (KB). The default value is 4096 KB.
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
usermultitonovalattr	Specifies the comma separated list of user entry attributes for which value can go from some value (multiple or single) to no value. This parameter does not come pre-configured in the adc.ini file. User has to configure this parameter. The attribute names listed against this parameter should be the attribute names used in the external data source and one should not specify the attribute names used at the Connector View end. For example: usermultitonovalattr=mail,telephoneNumber
groupmultitonovalattr	Specifies the comma separated list of group entry attributes for which value can go from some value (multiple or single) to no value. This parameter does not come pre-configured in the ini file. User has to configure this parameter.The attribute names listed against this parameter should be the attribute names used in the external data source and one should not specify the attribute names used at the Connector View end. For example: groupmultitonovalattr=member,description
fulldumpfreq 2	Specifies that at every nth scheduled synchronization, the connector should run in the ‘Full Dump’ mode. This is done to ensure data is in a consistent state and performs the ‘add-back’ operations in the Incremental mode. For instance, when fulldumpfreq = 5, the connector will run in the ‘Full Dump’ mode, at every 5th scheduled sync. To disable fulldump mode, set fulldumpfreq to -1.

1If the domain controller’s password is changed, you must create a new instance of the associated connector.

2The connector can run in three modes: Incremental, Find Delete and Full Dump. In Incremental mode, the connector detects only new and modified entries in Active Directory and flows it to the Connector View. This mode does not detect deletes. In the Find Delete mode, the connector only finds deleted entries in Active Directory and deletes the corresponding entries in the Connector View. In Full Dump mode, all entries in Active Directory are flowed to the Connector View. This ensures all entries are correctly in sync. The ‘fulldumpfreq’ and ‘finddeletedfreq’ parameters in the ADC.INI file are used to control when Full Dump and Find Delete modes are used. If the Full-Dump and Find-Delete mode clash, Full-Dump takes priority and gets executed. The default mode is Incremental.

To add the instance as a Participating View

Right-click the Participating Views object.

Click Add Participating View. The ‘Select View’ dialog box displays.

Select the Connector View to add or participate in a join/synchronization with the Meta View.

Once complete, click OK. The view is added to the 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 2, "Working with Views."

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 the Contents of the Active Directory Meta View.

Choose Object > New > User. The ‘Create New User’ dialog box displays.

Provide input in the required fields. A default user ID is generated when you enter the first and last names. See the section on User Entries for attribute conventions and restrictions.

Click OK. The user name appears in the right pane of the Meta-Directory console.

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 in "User Entries" and "Group Entries".

To modify an Active Directory user in the Meta View

Click Contents of the Active Directory Meta View.

Double-click the Active Directory user to modify.

The ‘Edit Entry’ dialog box displays.

Modify the fields as required, and then click OK.

Configuring Connector Rules

You can configure the following types of rules for the Active Directory connector:

Attribute Flow

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 - is the minimum set of attributes necessary to flow data

Complete Attribute Set for Default Schema - represents the complete Directory Server schema

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 described in the next section.

If you select one of the configurations, remove a few attributes, and then save the configuration. You cannot revert to the original list of attributes by clicking Insert Defaults. Click this option to display a list of default mappings that you can delete or modify.

Default Values

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 described in the next section.

Filters

The connector uses filtering rules to selectively exclude entries from the synchronization process.

To configure connector rules, see "Configuring Attribute Flow Rules", "Configuring Default Attribute Value Rules", and "Creating Filter Rules".

Configuring a Connector Instance

Consider the following procedure an extension of the comprehensive configuration procedures in "Configuring 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. To manually configure, go to Step 2.

Select the connector instance to specify its attributes.

The ‘General’ window displays.

From the list, select the attribute flow, filter, and default value configurations. The displayed values 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 required, before saving the configuration. The minimum configuration consists of the following attributes:

Table 7-3 Description of the attributes and their applicable user and user groups
Application	Attributes
Users	cn objectclass sn uid
Local and Global Groups	cn objectclass

See Table 7-4 and Table 7-5 for the complete list of external attributes.

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:

uid
cn
sn
objectclass
mail

All 37 default attributes should synchronize from the Connector View to Active Directory.

Select the operation to perform.

Once complete, click Save, and then go to Step 3.

Optional: Manually configure the attribute flow by doing the following:

Select the Active Directory Connector, and then select the Attribute Flow tab, as described in "Configuring Attribute Flow Rules".

Click New and enter a new configuration name, and then click OK.

Click Insert.

The ‘Insert Attribute Mappings’ dialog box displays. For both mapping types (‘locally owned objects’ and ‘Connector View-owned objects’), map each attribute for both the flow directions (to Connector View and from Connector View).

For example, the description attribute being mapped to itself for a flow direction to the Connector View. This should be repeated for a flow direction from the Connector View:
Figure displays the ’Insert Attribute Mapping’ dialog. It shows the ’Description’ attribute being mapped to itself for a flow direction.

Once complete, click Save. Then, choose View > Refresh.

Select the Active Directory Connector instance.

The ‘General’ window displays.

From the ‘Attribute Flow Configuration’ list, select the attribute flow configuration you created (Step b). The name is available in the list after you refresh (Step d).

Select the appropriate filters and default values from the lists.

Select the operation to perform and click Save.

Configure other options as described in the "To configure the schedule from and to Connector Views" section.

Restarting the Connector Instance

You must restart the connector instance to activate the configuration. Both instance-specific and shared configurations is not effective for a particular instance until you restart the instance. If the entries you are saving already exist in an Active Directory Connector View, see "Data Flow for User and Group Entries" for information.

To restart a connector instance

Right-click the connector instance, and click Yes when prompted.

A confirmation message displays.

Right-click the connector instance, and click Start Server.

A confirmation message displays.



Note	To start the connector, you must be a member of the Administrators group on the primary domain controller.

Implementing the Configuration

After the Join Engine started and the Connector View enabled, the data can then 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 retro-changelog plug-in in the Directory Server configuration.

To start the Join Engine

Select the Join Engine object from the navigation tree and right-click.

Click Start Server. A confirmation message displays.

You can also start the server from the Sun ONE Console. To do this, select the Join Engine object and right-click. Click Start Server.

Enabling the Connector View

From the Meta-Directory window, select the Status tab.

Click the Join Engine object. The ‘Operations’ window displays.

Select the Participating View to enable.

Select Enable from the ‘Operation’ list, and then click Submit Request.

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.

Select Refresh from the ‘Operation’ list, and then select either Meta View or Connector View from the Traverse menu list.

Click Start.

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 Meta-Directory window, select the Status tab.

Click the NT Domain connector instance object. The ‘Operations’ window displays.

From the ‘Updates to the’ list, select either External Directory or Connector.

Click Start. The ‘Modify Task Status’ dialog box displays if you are refreshing the Connector View.

If you are refreshing the external directory, the following status dialog box displays:
Figure shows the ’Modify Task Status’ dialog box.

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

Logs from the following locations help you monitor the connector status:

UTC Log	InstallDir/adc-ViewName/logs/meta-date-index.log
Accessor Utility Log	InstallDir/adc-ViewName/logs/acc-date-index.log
Perl Script Log	InstallDir/adc-ViewName/logs/adcpl-date-index.log
Task Script	InstallDir/adc-ViewName/logs/adc-texttype.txt

For example, a Perl log file could have an entry as:

adcpl-20010605-01.log

Errors you may encounter in the Accessor Utility Log are as follows:

8007202A - Invalid domain or user name

8007203A - Cannot contact Active Directory

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:

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.

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.

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: inetOrgPerson
sn: user_second_name

For the ADSpecific schema, the structure would be as follows:

dn: cn=user_cn,cvroot_dn
cn: user_cn
objectclass: mdsADtop
objectclass: mdsADperson
objectclass: mdsADorganizationalPerson
objectclass: mdsADUser

Note the following restrictions:

A user name cannot consist solely of periods (.), spaces, or the at (@) sign. Also, leading spaces or periods(.) or # are not supported in user name.

When flowing user name with special characters(as specified in RFC 2253) from Connector View, they should be escaped with '\'.

Table 7-4 describes the available attributes for the user entries in ‘complete attribute set mapping’ for default schema mode. Refer to your Active Directory documentation for more information about these attributes.

Table 7-4 Attributes for User Entries
departmentnumber	homephone
description1	telephonenumber
facsimiletelephonenumber	l
homepostaladdress	employeeid
o	mobile
ou	usercertificate
objectclass	physicaldeliveryofficename
pager	cn
postalcode	mail1
postofficebox	street
displayname	postaladdress
sn	destinationindicator
st	givenname
usermimecertificate	title
employeetype	initials2
internationalisdnnumber	preferreddeliverymethod
registeredaddress	teletexterminalidentifier
telexnumber	uid
x121address

1‘Description’ and ‘mail’ attributes are declared as multi-valued attributes in Sun ONE Directory Server, however, these attributes are considered as single-value attributes in Microsoft Active Directory.

2‘Initials’ attribute in Microsoft Active Directory can have maximum of 6 characters only.

Enabling or Disabling a User Account

Enabling or disabling the User Account can be controlled by providing a valid value for the ‘mdsaduserAccountControl’ attribute of the User entry. (For valid values of this attribute, see the Microsoft’s Active Directory documentation.) This is possible only if the connector instance is configured with ‘ADSpecific’ schema. There is no validation for the attribute values on the Connector View side, and all values would follow the Active Directory standards while flowing to and from the Active Directory.

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 Active Directory 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
cn: groupname
objectclass: top
objectclass: groupOfNames

For the ADSpecific schema, the structure would be as follows:

dn: cn=groupname, cvroot_dn
cn: groupnam
objectclass: mdsADtop
objectclass: mdsADgroupOfNames

The following restriction applies to group entries:

A group name cannot consist solely of periods (.), spaces, or the at (@) sign. Also, leading spaces or periods(.) or # are not supported in group name.

When flowing group name with special characters(as specified in RFC 2253) from Connector View, they should be escaped with '\'.

Table 7-5 shows the available attributes for the group entries in ‘complete attribute set mapping’ for default schema mode. Refer to your Active Directory documentation for more information about these attributes.

Table 7-5 Attributes for Group Entries
cn	uniquemember
description	objectclass

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.

Install the Connector

Ensure that Sun ONE Directory Server 5.2 and Sun ONE Meta-Directory 5.1.1 is installed.

Create a Connector View instance.

During instance creation:

From the Sun ONE Console window, right-click 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 7-1.

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. Use default parameters and values.

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 Active and click OK. The view is added to the Meta-Directory tree.

Provide authorization. For more details, see "Setting Access Permissions".

Configure Connector Rules

Configure attribute flow.

Click on the Active Directory connector. The Attribute Flow tab window appears.

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.

Configure default attribute rules.

Click on the Default Values tab. The Default Values window appears.

Click New.

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

Configure filters.

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

Select From Connector View.

Filter excluded data:

Provide a list of subtrees to exclude by selecting All Subtrees Except, then clicking Add. The Sub-tree DN dialog box appears.

Specify a subtree to exclude, such as o=madisonparc,c=us, then click OK. The subtree appears in the list box.

With this filter, entries in all subtrees that are not specifically excluded are included, no matter how you set the associated entry-level filters.

Filter back entries from the excluded subtrees using entry-level filters. Select the subtree you just created, select ‘Exceptions to Above Rule’, then click Add. The Entry RDN dialog box appears.

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.

Click Save.

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 Filter Configuration, select ActiveExclude.

For Default Values Configuration, select ActiveDefault.

For Operation, select “Only receive updates from the Connector View.”

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