ADC Filtering and Object-Matching

Fine-tune directory synchronization

By now, you're probably familiar with the operation of the Active Directory Connector (ADC). In short, the ADC is a utility that uses connection agreements (CAs) to define an instance of synchronization between the Exchange Server 5.5 Directory Service (DS) and Active Directory (AD). Understanding the operation of the ADC is an essential part of planning for any migration from Exchange Server 5.5 to Exchange 2000 Server.

At first glance, the ADC's granularity of operation seems limited. From the Exchange Server 5.5 DS, you select the contents of one or more Recipients containers to synchronize with one organizational unit (OU) in AD. Similarly, from AD, you select the contents of one or more OUs to synchronize into one Recipients container in the Exchange Server 5.5 DS.

If the source Recipients container or OU contains only mailbox entries or user objects, you must synchronize all those mailbox entries or user objects; if the source Recipients container or OU contains only custom recipients or contacts, you must synchronize all those custom recipients or contacts. Distribution lists (DLs) and groups have a similar requirement.

Sometimes, however, you might want to synchronize just a subset of the objects within a Recipients container or an OU. For example, you might want to exclude Exchange Server 5.5 mailboxes that multiple users share and that aren't associated with a particular Windows NT 4.0 account. Included in this category are resource mailboxes used for conference room bookings that share a common NT 4.0 account in the Exchange Server 5.5 environment. These mailboxes are represented differently in Exchange 2000 and thus, you must synchronize them carefully into AD. Similarly, when you synchronize objects from AD to the Exchange Server 5.5 DS, you might want to select only those mail-enabled user objects in a particular geographic location, even though they might all reside in the same OU in AD.

Some less-well-known ADC configuration options give you more flexibility with ADC synchronization. Specifically, I show you two ways to control the selection of objects for ADC synchronization: Lightweight Directory Access Protocol (LDAP) search filters and ADC custom object matching.

The ADC out of the Box
A CA's default behavior is restrictive because it limits how selective you can be about objects you want to synchronize. Figure 1 shows a typical set of configuration settings on the Site Connection Agreement Properties dialog box's From Exchange tab. You use these settings to synchronize the contents of the Exchange Server 5.5 DS Recipients container to the AD Users OU. As the settings show, this intraorganizational CA synchronizes mailboxes, custom recipients, and DLs to AD. In AD, these synchronized objects appear as user objects, contacts, and distribution groups, respectively.

However, you can be more selective with what you synchronize between the directories. For example, if you want to synchronize only mailboxes from the Recipients container, you can clear the check boxes specifying that you want to synchronize custom recipients and DLs. In the opposite direction, you can use the same options on the From Windows tab to control synchronization of users, contacts, and groups to the DS.

How the ADC Uses LDAP
Let's assume that you've defined several mailbox objects in the Exchange Server 5.5 Recipients container, as Figure 2 shows. Four mailbox objects appear in the Recipients container. In three of those mailboxes, the Office attribute value is Valbonne, whereas the Office attribute value for Donald Livengood's mailbox is Atlanta.

Under ordinary circumstances, the CA with the properties that the screen in Figure 2 defines would synchronize all four of these mailbox objects to AD. Neither the CA nor the ADC has any configuration options anywhere on their Properties dialog box that let you specify that you want to synchronize only a subset of these mailboxes. What do you do if you want the CA to synchronize only the Valbonne mailboxes but ignore the Atlanta mailbox?

The ADC operates by executing an LDAP query on the Exchange Server 5.5 DS with a search base that specifies the containers to use as sources for the CA. This search base is the containers in the Exchange recipients containers box that Figure 1 shows. By default, the LDAP query selects all mailboxes (if you selected the Mailboxes object), but you can customize the LDAP query so that it selects only some mailboxes. Specifically, the settings that Figure 1 shows define the following default LDAP search for the CA:

(|(objectclass=organizationalPerson)(objectclass=remote-address)(objectclass=groupOfNames))

This default search filter states that the CA should use a mailbox (organizationalPerson), a custom recipient (remote-address), or a DL (group-OfNames) as a valid object for synchronization.

Using a Customized LDAP Search Filter
To refine the synchronization process to synchronize only Valbonne objects, you can modify this CA's LDAP search filter so that it reads

(&(|(objectclass=organizationalPerson)(objectclass=remote-address)(objectclass=groupOfNames))(physicalDeliveryOfficeName=Valbonne))

This search filter dictates that the ADC process only mailboxes, custom recipients, or DLs that have their Office attribute (i.e., physicalDeliveryOfficeName in LDAP terminology) set to the value Valbonne. You can find the LDAP names of Exchange Server 5.5 DS attributes by running the Microsoft Exchange Administrator program in raw mode and looking at the description of the attribute in question under View Raw Directory, Schema. Similarly, you can use ADSI Edit to look at an attribute's schema definition in AD to determine its LDAP name.

You could further refine this search filter so that the ADC synchronizes all custom recipients or DLs, but only mailboxes in Valbonne, by using the following expression:

(|(objectclass=remote-address)(objectclass=groupOfNames)(&(objectclass=organizationalPerson)(physicalDeliveryOfficeName=Valbonne)))

The sidebar, "Understanding LDAP Search Filters," page 6, explains the structure of LDAP search filters. See "Related Articles," page 7, for more resources about this topic.

Setting an LDAP Search Filter on a CA
Because the ADC management interface doesn't offer any mechanism for setting properties on either a CA or the ADC to control the LDAP search filter for a particular CA, to customize the search filter on a given CA, you must directly modify objects that control the ADC's synchronization behavior in AD. Any CAs that you define for a given ADC are represented in AD, just like a user object, contact, or group. Exchange 2000 stores its configuration information in AD's configuration naming context (NC), and the ADC stores configuration information for itself and its CAs in the configuration NC, too. Drilling down through AD to the Microsoft Exchange branch, as Figure 3 shows, you find the entry for the CA; in the case I'm discussing, the entry is the Site Connection Agreement.

Although a CA object has many associated attributes, the msExchServer2SearchFilter attribute defines the search filter the ADC uses when it selects objects for synchronization from the Exchange Server 5.5 DS to AD. (Conversely, the msExchServer1SearchFilter defines the search filter the ADC uses when it synchronizes objects from AD to the Exchange Server 5.5 DS.)

The only way to set the value of this attribute is to manipulate the attribute directly in AD by using a tool such as ADSI Edit or the AD administration tool (ldp.exe). Both tools are available in the Windows 2000 Support Tools folder on the Win2K CD-ROM.

Using ADSI Edit, select the Site Connection Agreement and right-click to open the Properties dialog box, which Figure 4 shows. Select the msExchServer2SearchFilter attribute, then set its value by typing the search filter into the Edit Attribute field and clicking Set. The next time you run the CA, the search filter will be active and objects that correspond to its scope will be able to participate in ADC synchronization.

Default ADC Object-Matching Behavior
The ADC has a default set of matching rules that control the actions that the ADC takes when it processes an object in one directory system and attempts to match it with an object in another directory system. When processing objects in AD, for example, the ADC attempts to match an AD object with a corresponding object in the Exchange Server 5.5 DS by searching on a fixed set of attributes. These matching rules work for simple synchronization cases when the environment is straightforward.

For any Exchange Server 5.5 DS object that the ADC processes, the ADC searches first through AD by using the globally unique ID (GUID—Object-GUID in LDAP nomenclature) attribute of an Exchange Server 5.5 object to look for an object in AD that has a matching GUID. (The Object-GUID attribute is set on the Exchange Server 5.5 object if the object has previously been replicated to the Exchange Server 5.5 DS from AD.) If the ADC finds a match, the ADC assumes that the AD object corresponds to the DS object and synchronizes attribute information from the DS object to the AD object.

If the ADC doesn't find a match, it tries a new search by using the distinguished name (DN) of the DS object against the legacyExchangeDN attribute of the AD object. Again, if the ADC finds a match, the ADC merges attribute information from the DS object with the AD object.

If the ADC hasn't found a match after the DN search, the ADC uses the Primary NT Account attribute (Assoc-NT-Account) of the DS object to match against an object in AD with a matching SID. If the ADC finds a match by using this technique, then it synchronizes attribute information. Finally, if the ADC doesn't find an object by using any of the default ADC object matching rules, the ADC will create a new object in AD to represent the Exchange Server 5.5 DS object.

A similar process takes place in the opposite direction when the ADC synchronizes from AD to the Exchange Server 5.5 DS. The ADC searches through the DS looking for objects in AD with an Object-GUID attribute that matches the GUID of the current AD object. If this match fails, the ADC matches the legacyExchangeDN of the AD object against the DN of the DS object. The last match uses the SID of the AD object against the SID of a DS object. If any of these matches are successful, the ADC merges attribute information between the two objects. If the matches fail, then the ADC creates a new object in the Exchange Server 5.5 DS to represent the AD object.

Using Custom Object-Matching Rules on the ADC
An LDAP search filter lets you specify which objects you'll let the ADC process during a synchronization run between the Exchange Server 5.5 DS and the AD, or vice versa. In addition to using search filters, you can use an alternative method to control the objects that you want the ADC to process. Whereas the ADC applies LDAP search filters for each CA, you can set custom object-matching rules on the ADC itself. Setting a custom matching rule means that the rule applies to all CAs homed on a particular ADC. These custom object-matching rules override the ADC's default object-matching rules.

The ADC has an interface with which you can define simple customized matching rules. You access the interface by right-clicking Active Directory Connector Management from within the Microsoft Management Console (MMC) Active Directory Manager snap-in, then selecting Properties. You can set custom matching rules for synchronization from Exchange or from Windows by selecting the appropriate tab. Balance any rules that you set in one direction with a corresponding rule in the opposite direction to ensure synchronization symmetry.

For example, Figure 5 shows a new custom matching rule that I created that matches the Primary NT Account (Assoc-NT-Account) attribute of an Exchange Server 5.5 DS object against the SID History attribute of an AD object. This custom matching rule is useful when you've migrated accounts from NT domains to Win2K domains by using the migration tools that use the ClonePrincipal API. This API preserves the old SID value of the NT 4.0 account in the SID History attribute of the new Win2K account. Examples of such tools include Microsoft's Active Directory Migration Tool (ADMT), FastLane Technologies' DM/Suite, BindView's Direct Migrate 2000, and NetIQ's OnePoint Suite. In such environments, the original NT 4.0 account might have been the Primary NT account associated with the Exchange Server 5.5 mailbox. After you'd migrated the NT account to Win2K, the ADC would fail to match an Exchange Server 5.5 mailbox object against the migrated Win2K object (the new Win2K object has a different SID) unless you used this form of matching rule against the SID History attribute.

You can select a variety of attributes from an Exchange Server 5.5 DS object to match against a similar variety of attributes from an AD object to suit your interoperability environment. For example, you could match the Exchange Server 5.5 mailbox alias (Mail-nickname) against the Win2K account name (SAM-Account-Name), as Figure 6 shows, if you're confident that these attributes are unique and link the Exchange Server 5.5 mailbox with the new Win2K account. Similarly, other attributes to match with include mail address attributes and the complete set of 15 extension attributes from the Exchange Server 5.5 DS. These attributes are useful matches if your environment and migration technique use custom attributes to store employee ID numbers or Social Security numbers.

Defining Custom Matching Rules
When you use the interface I just described to set custom matching rules, you store the logic associated with the rules in AD as attributes of the Default ADC Policy. Figure 3 shows where this AD object resides in the AD hierarchy. For the custom matching rule I just defined, which matches the Primary NT Account attribute with the SID History attribute, this rule is stored in the msExchServer2ObjectMatch attribute. Figure 7 shows a view of this attribute.

The msExchServer2ObjectMatch attribute stores custom matching rules that the ADC uses when it matches objects from the Exchange Server 5.5 DS to AD; the msExchServer1ObjectMatch attribute stores matching rules the ADC uses from AD to the Exchange Server 5.5 DS. The value of the msExchServer2ObjectMatch attribute, which Figure 7 doesn't display fully, specifies the matching rule. The full text of the rule is

ObjectMatch###Assoc-NT-Account#sIDHistory#sid_match#

Similarly, if you use this interface to define multiple custom matching rules, the ADC stores these rules in the msExchServer2ObjectMatch attribute. For example, if you've defined both matching rules, such as the rules that Figure 5 and Figure 6 show, the attribute value is

ObjectMatch###Assoc-NT-Account#sIDHistory#sid_match#ObjectMatch###UID#sAMAccountName#sid_match#

The examples I describe in the next section all rely on creating or modifying the matching rules set on the msExchServer2ObjectMatch attribute. Just as you use ADSI Edit to view these rules, you use ADSI Edit to set new values on the attribute.

Matching Rule Syntax
The syntax of the custom matching rules is

name#soc#toc#sa#ta#flags#

where

The object class values are optional. If you leave an object class blank, then all objects will be valid for processing by the particular rule. If you want to restrict the types of objects to which a rule can apply, you must specify the complete hierarchy of the object class by using a dollar sign delimiter. For example, if you want the ADC to apply the SID History matching rule, which Figure 5 shows, only against user objects in AD, you must change the rule to read

ObjectMatch##user$organizationalPerson$person$top#Assoc-NT-Account#sIDHistory#sid_match#

Matching Rule Flags
Each matching rule has an associated flag that controls the processing. In the example I just described, the sid_match flag lets matching proceed on the basis of SID comparison. The presence of a guid_match flag assumes that the objects the ADC is synchronizing have previously been matched (i.e., in the AD-to-Exchange Server 5.5 DS direction).

For example, the default matching rule that controls how the ADC matches Exchange Server 5.5 DS objects and synchronizes them to AD is

ObjectMatch###Assoc-NT-Account#ObjectSID#sid_match EscapeBinaryBlob#

This matching rule attempts to match the NT 4.0 SID of the Exchange Server 5.5 DS object with the SID of an object in AD. You use the EscapeBinaryBlob flag with the sid_match or guid_match flags when the source attribute is in ASCII format but the target attribute is in binary format. If the ADC doesn't find a match between two objects that already exist, the ADC will attempt to create a new object in AD to correspond with the DS object.

However, what if you want to prevent this behavior? For example, you might decide you don't want to synchronize DS objects that have an Office attribute set to Atlanta. To prevent synchronization, you can change the ruleset to

ObjectMatch###Assoc-NT-Account#ObjectSID#sid_match EscapeBinaryBlob#ObjectMatch###physicalDeliveryOfficeName#"Atlanta"#veto-previous#

The veto and veto-previous flags tell the ADC not to replicate the object that it's processing if it finds a match on the source attribute and the target attribute value. The veto flag (which doesn't appear in this rule) tells the ADC not to replicate the object and to abandon all matching for that object. The veto-previous flag signifies that if the current match is true, the ADC should ignore the previous matching rule but continue match processing with the next matching rule.

What this set of rules signifies is that if the Office attribute matches the text string Atlanta, the ADC ignores the previous rule (which defines the matching between SIDs). In this case, the ADC won't synchronize the Atlanta mailbox or create a corresponding user object in AD. Similarly, you could add further matching rules to, say, ignore all Exchange Server 5.5 DS objects that have Custom Attribute 5 set to IgnoreADC and not have those objects replicate to the AD. This matching rule would read

ObjectMatch###Assoc-NT-Account#ObjectSID#sid_match EscapeBinaryBlob#ObjectMatch###physicalDeliveryOfficeName#"Atlanta"#veto-previous#ObjectMatch###Extension-Attribute-5#"IgnoreADC"#veto-previous#

Or you could specify that the ADC ignore any DS objects that have any value set in Custom Attribute 6:

ObjectMatch###Assoc-NT-Account#ObjectSID#sid_match EscapeBinaryBlob#ObjectMatch###physicalDeliveryOfficeName#"Atlanta"#veto-previous#ObjectMatch###Extension-Attribute-5#"IgnoreADC"#veto-previous#ObjectMatch###Extension-Attribute-6#NotNULL#veto-previous#

The ADC has some default matching-rule behavior, such as what I just described, to deal with objects that have the value NTDSNoMatch in Custom Attribute 10. In such cases, the ADC won't create user objects in AD for these objects.

As you experiment with these search filters and object-matching rules, you might want to enable ADC diagnostic logging. To turn on logging, right-click the MMC Active Directory Connector snap-in, then select Properties, Diagnostic Logging. The logs of ADC operations might help you understand what is happening during your customized ADC synchronizations.

Some Closing Thoughts
The ADC is a powerful tool for controlling objects you want to synchronize from one directory to another. In this article, I've looked primarily at controlling the flow of objects from the Exchange Server 5.5 DS to AD. However, you can use a similar set of attributes on CAs and on the ADC policy to achieve the same sophistication in controlling object flow from AD to Exchange Server 5.5. Using LDAP search filters or custom matching rules affords those designing and overseeing migrations from Exchange Server 5.5 to Exchange 2000 great flexibility for sequencing object synchronization and controlling the synchronization of resource mailboxes.