LDAP Referrals

When a requested object exists in the directory but is not present on the contacted domain controller, name resolution depends on that domain controller's knowledge of how the directory is partitioned. In a partitioned directory, by definition, the entire directory is not always available on any one domain controller.

An LDAP referral is a domain controller's way of indicating to a client application that it does not have a copy of a requested object (or, more precisely, that it does not hold the section of the directory tree where that object would be, if in fact it exists) and giving the client a location that is more likely to hold the object, which the client uses as the basis for a DNS search for a domain controller. Ideally, referrals always reference a domain controller that indeed holds the object. However, it is possible for the referred-to domain controller to generate yet another referral, although it usually does not take long to discover that the object does not exist and to inform the client. Active Directory returns referrals in accordance with RFC 2251.

In its Configuration container, every domain controller has information about the other domains in the forest. When an operation in Active Directory requires action on objects that might exist in the forest but are not located in the particular domain that is stored on a domain controller, that domain controller must send the client a message that describes where to go to continue this action — that is, the client is "referred" to a domain controller that is presumed to hold the requested object.

Clients do not need to know the name or location of a child domain in order to contact a domain controller in that domain. They can query the root domain and reach the appropriate domain controller by being referred there. Two situations generate this type of domain controller response:

  • The base distinguished name of the operation is not in this directory, but the domain controller has knowledge of another LDAP directory where it might be found (an "external referral").

  • The base distinguished name of the operation is in this directory, but the operation requires proceeding into portions of the directory tree that are not stored on this domain controller (a subordinate referral).

Every domain controller contains information (called "knowledge") about how the directory is partitioned, and this information can be used with DNS to find the correct Active Directory domain.

Knowledge References

Active Directory stores information about the existence and location of directory partitions, including the names of the directory partitions, the name of the server that is holding read-only copies (partial directory partitions stored on Global Catalog servers), and the name of the server that is holding writable copies (full directory partitions. Active Directory uses this information (known as "knowledge references") to generate referrals to other domain controllers.

Active Directory uses three kinds of knowledge references to generate referrals to other domain controllers:

  • A subordinate reference, which is knowledge of a directory partition (or partitions) directly below a directory partition that is held by the domain controller.

  • A cross-reference, which is knowledge of one directory partition and which is stored in a cross-reference object. On a specific domain controller, the combination of all cross-references provides knowledge of all directory partitions in the forest, regardless of their locations in the directory tree.


The state of cross-reference knowledge at any specific time is subject to the effects of replication latency.

  • A superior reference, which is knowledge of a specifically designated referral location that is used when the domain controller has no knowledge of the search base.

Knowledge references form the glue that holds the pieces of the distributed directory together. Because Active Directory is logically partitioned and directory partitions are the discrete components of the directory that replicate between domain controllers, either all objects in a directory partition are present on a particular domain controller or no objects in the directory partition are present on the domain controller. For this reason, references have the effect of linking the partitions together, which allows operations such as searches to span multiple partitions.

In Active Directory, referrals are generated when the client requests that the directory locate an object where, based on the position at which the search begins, no copy exists in a local directory partition. When Active Directory can determine definitively that no such object exists in the directory (rather than that it might exist somewhere else even though no copy exists here), instead of sending a referral, the directory returns an error message to the client that no such object exists in the forest.

For more information about replication of directory partitions, see "Active Directory Replication" in this book.

Subordinate References

When a client requests a search, the domain controller searches all objects at or below the search base, within the directory partition that the domain controller holds. If a subtree search has a search base that includes child partitions, the domain controller uses subordinate references to return referrals (called subordinate referrals ) to these partitions.

Subordinate referrals are returned as part of the data that is returned from the base distinguished name partition. The referral contains the distinguished name of the subordinate directory partition and the access point to which queries can be referred. An access point consists of a DNS name and a port number, which is the information that is required to contact a specific LDAP server. Access points are generated from information contained in the cross-reference object.


Cross-references are stored as directory objects of the class crossRef that identify the existence and location of all directory partitions, irrespective of location in the directory tree. Cross-references enable every domain controller to be aware of all directory partitions in the forest, not only the partitions that it holds. Because these objects are stored in the Configuration container, the knowledge that they store is replicated to every domain controller in the forest.

Values for the following attributes are required for each cross-reference:

  • nCName. The distinguished name of the directory partition that the crossRef object references. ("nC" stands for "naming context," which is a synonym for "directory partition.") The combination of all of the nCName properties in the forest defines the entire directory tree, including the subordinate and superior relationships between partitions.

  • dNSRoot . The DNS name of the domain where servers that store the particular directory partition can be reached. This value can also be a DNS host name.

Cross-reference objects are used to generate referrals to other directory partitions in the forest and to external directories.

Cross-reference objects are created in two ways:

  • Internally by the system to refer to known locations that are within the forest.

  • Externally by administrators to refer to locations that are external to the forest.

Internal Cross-References

An internal cross-reference is an object that is created by the system. For every directory partition in a forest, there is an internal cross-reference object in the Partitions container (cn=Partitions,cn=Configuration,dc= ForestRootDomain ). When you create a new forest, the Active Directory Installation Wizard creates three directory partitions: the first domain directory partition, the configuration directory partition, and the schema directory partition. For each of these partitions, a cross-reference object is created automatically. Thereafter, when a new domain is created in the forest, another directory partition is created and the respective cross-reference object is created. Because these cross-reference objects are located in the Configuration container, they are replicated to every domain controller in the forest, and thus every domain controller has knowledge of the name of every partition in the forest (as well as their superior and subordinate relationships to each other). By virtue of this knowledge, any domain controller can generate referrals to any other domain in the forest, as well as to the schema and configuration directory partitions.

External Cross-References

An external cross-reference is a cross-reference object that can be created manually to provide the location of an object that is not stored in the forest. If your LDAP clients submit operations for an external portion of the global LDAP namespace against servers in your forest, and you want your forest's servers to refer the client to the correct location, you can create a cross-reference object for that directory in the Partitions container.

There are two ways that external cross-references are used:

  • To reference external directories by their disjoint directory name (a name that is not contiguous with the name of this directory tree). In this case, when you create the cross-reference, you create a reference to a location that is not a child of any object in the directory.

  • To reference external directories by a name that is within the Active Directory namespace (a name that is contiguous with the name of this directory tree). In this case, when you create the cross-reference, you create a reference ** to a location that is a child of a real directory object.


An external directory that is stored on a Windows 2000–based domain controller does not require an explicit cross-reference object. Because the domain component (dc=) portions of the distinguished names of all Windows 2000 domains match their DNS addresses and because DNS is the worldwide namespace, all Windows 2000–based domain controllers can generate external referrals to each other automatically.

Creating External Cross-References

The only time you have to create a cross-reference object is when you want to extend a search to a directory outside the forest that is a non-Windows 2000 LDAP directory service In this case, you can use an LDAP editor, such as ADSI Edit or Ldp, to create objects of the class crossRef in the Partitions container that reference external directories.


To use ADSI Edit and Ldp, install the Support Tools that are located in the Support\Tools folder on the Windows 2000 Server operating system CD. To install the tools, double-click the Setup icon in that folder. For information about installing and using the Windows 2000 Support Tools and Support Tools Help, see the file Sreadme.doc in the Support\Tools folder of the Windows 2000 operating system CD. For more information about using ADSI Edit and Ldp, see Microsoft Windows   2000 Resource Kit Tools Help.

When you create a cross-reference object, you must provide the values for three attributes:

cn    The name that describes the directory. For example, for the domain noam.reskit.com, your cn value might be "noam" or something else that describes that domain, such as "NorthAmerica."

nCName    The distinguished name of the domain directory partition to which your cross-reference refers. If the domain name is noam.reskit.com, the value of nCName would be dc=noam,dc=reskit,dc=com.

dnsRoot    The DNS host name of an LDAP server in the domain that is identified by nCName (for example, server1.noam.reskit.com). The value of dnsRoot can also be the domain name if you do not want to specify a server.


You must be able to resolve ("ping#34;) the name in dnsRoot , which does not necessarily name another Windows 2000–based system; it might be the DNS address of an LDAP server instead of a domain controller. If the directory partition is a Windows 2000 domain from another forest, automatically generated knowledge is usually sufficient and no external cross-reference is required.

You can use either ADSI Edit or Ldp to create cross-reference objects in the Configuration container. However, Ldp requires that you provide the distinguished name of an object and its mandatory and optional attribute names and values when you add the object to Active Directory. For more information about using Ldp, see Microsoft Windows   2000 Resource Kit Tools Help.

ADSI Edit provides a convenient graphical user interface for creating cross-reference objects.

To use ADSI Edit to create a cross-reference object

  1. In ADSI Edit, expand the Configuration container.

  2. Right-click the CN=Partitions container, click New , and then click Object .

  3. For Select a class , you can create objects of only class crossRef , which is already selected. Click Next .

  4. For the cn attribute, in the Value box, type a name that describes the location, and then click Next .

  5. For the nCName attribute, in the Value box, type the distinguished name for the external domain, and then click Next .

  6. For the dnsHostname attribute, in the Value box, type a DNS name for the server that hosts the domain directory partition, or type the domain name.

  7. When you are sure that your entries are correct, click Finish .

To make use of cross-references, clients must be enabled to follow ("chase") referrals that are returned. Windows Address Book chases referrals by default. In Ldp, you can specify Chase Referrals in the search options. When you are using ADSI programmatically (for example, by using Active Data Objects [ADO] to search), you must specify whether to chase referrals. For more information about using ADSI programmatically, see the Microsoft Platform SDK link on the Web Resources page at https://windows.microsoft.com/windows2000/reskit/webresources .

Creating an External Cross-Reference for an External Location

To create a cross-reference to an external directory by referencing an external location, you give the nCName attribute a value that is the name of the actual external directory. For example, an external LDAP directory might use X.500 naming (such as o= Organization Name ,c= Country/Region ), which would be used for the value of the nCName attribute. Queries for this directory must specify the external object by name in the search base distinguished name. A request for a referral to such a location might come in the form of an LDAP Uniform Resource Locator (URL) embedded in an e-mail message or from an application that specifically names the directory distinguished name.

Creating an External Cross-Reference for an Internal Location

If you want a subtree search of a portion of your directory to always include an external LDAP directory that is not a Windows 2000 directory service, you can create a cross-reference to the external directory for an internal location. To create an internal location that references an external directory, give the nCName attribute of the cross-reference object a value that is an immediate child object of an existing directory object and that also matches the distinguished name of the external directory. Choose the location according to where you want the external directory to be locatable in Active Directory.

This type of cross-reference is especially useful for smoothly integrating dynamic directories. For example, you might use an instant messaging application such as Microsoft® NetMeeting® conferencing software to publish a list of current or planned conference calls. LDAP is an effective protocol for querying such a published list; however, short-lived, highly volatile data is inappropriate for Active Directory storage. Therefore, you might use an in-memory, nonreplicated LDAP server (one that can store volatile data) at an arbitrary point in the namespace. This "volatile" directory service can then be configured to inhabit a name inside your company's Active Directory namespace and be made available to company users through a cross-reference for an internal location in Active Directory. Users can use this location to find the list of conversations by directory tree navigation.

Suppose that your domain name is reskit.com and you have installed your messaging application on a non-Active Directory–aware LDAP server named vds.it.reskit.com. On that server, you would create a directory for your volatile data, such as cn=conversations,dc=reskit,dc=com. Then, on your Active Directory domain controller, you would create a cross-reference object and use the following attribute values:

  • cn=conversation server

  • nCName=cn=conversations,dc=reskit,dc=com

  • dnsRoot=vds.it.reskit.com

When a user performs a subtree search of dc=reskit,dc=com, the client receives results from the Windows 2000–based domain controllers and also a subordinate referral to the volatile directory service server at vdserver.it.reskit.com, which instructs the client to continue the LDAP search from cn=conversations,dc=reskit,dc=com and below on that server.

Superior References

A superior reference is the distinguished name of a directory partition that is stored in the superiorDNSRoot attribute on the crossRef object for the forest root domain (the first domain created in the forest). A domain controller uses its superior reference to construct a referral only when a search base does not match any directory partition defined by the cross-reference objects. A superior reference contains no directory tree information; it consists of only an access point to which otherwise unanswerable queries can be referred.

By default, superiorDNSRoot does not store a value, but the directory uses the "dc=" components of the search base distinguished name to construct the equivalent of a superior referral. You can use the value in the superiorDNSRoot attribute to define a location to send all queries that cannot be resolved.

Ambiguous Name Resolution

Ambiguous name resolution (ANR) is the process of searching for a string value in a set of attributes by using one filter of the form (ANR= string ).

ANR Attribute Set

By default, the following set of attributes is evaluated when you enter an ANR search string in an LDAP filter:

  • givenName (first name)

  • sn (surname, or last name)

  • displayName (the name given the object when it is created)

  • RDN (the relative distinguished name of the object)

  • legacyExchangeDN (for enterprises that have upgraded a Microsoft® Exchange installation to a later version of Exchange that is synchronized with Active Directory, the distinguished name of the old Exchange mailbox that corresponds to the user in Active Directory)

  • physicalDeliveryOfficeName (for example, Building A, Suite 1234)

  • proxyAddresses (the collection of e-mail addresses over all e-mail address spaces that the Exchange server knows about)

When the (ANR= string ) filter is encountered, the filter is expanded to include a search of every attribute in the ANR set.

In Active Directory Users and Computers, you can use the Filter or Find option (on the shortcut menu or on the toolbar), and select the Custom and Advanced options to enter an ANR filter. Alternatively, you can use an LDAP editor, such as Ldp. From this LDAP client, you can implement filtered LDAP searches and view the LDAP responses. For more information about using Ldp, see "Active Directory Data Storage" in this book, and see Microsoft ® Windows ®  2000 Resource Kit Tools Help.

ANR Matching of an Embedded Space

For the givenName and sn attributes, if a space is embedded in the string presented in an ANR filter, the string is split at the first such space and each piece of the string is evaluated separately. This feature enables you to search for a user object by providing the first few characters of the first name ( givenName ) and the first few characters of the last name ( sn ). For example, the filter ANR=dar st finds all objects that have a givenName attribute value that begins with "dar" and an sn attribute value that begins with "st". In this example, the filter would return a user who has a givenName attribute of "Darlene" and an sn attribute of "Stuart," as well as a user who has a givenName attribute of "Darren" and an sn attribute of "Strong."

First/Last and Last/First Evaluation

For the attributes sn and givenName , when a space is embedded in the string presented in an ANR filter, the filter is expanded to find the values in both respective positions. For example, the filter (ANR=dav st) finds both the user David Strong and the user Steven Davis.

Expanded ANR Filter

When an ANR filter is encountered in an LDAP search, the filter is expanded to construct an OR operation on the string for every attribute in the ANR set. For the sn and givenName attributes, the first/last and last/first matching are also applied.

The ANR filter of the form (anr= xxxyyy ) is expanded to the following filter:

(| (displayName=xxx yyy*)

(givenName=xxx yyy*)

(physicalDeliveryOfficeName=xxx yyy*)

(proxyAddresses=xxx yyy*)...

(sn=xxx yyy*)

(& (givenName=xxx*)(sn=yyy*))

(& (givenName=yyy*)(sn=xxx*)))

The last three lines of the expanded filter are the portion of the filter that evaluates first name and last name.

Adding Attributes to the ANR Set

You can add attributes to the default ANR set by setting a flag on the attributeSchema object. By using ADSI Edit, connect to the schema and then open the properties on the attribute that you want to add. Set the searchFlags attribute value to a value that represents a bitwise OR operation of 4 and 1 to the existing value. The value  4 adds the attribute to the ANR set; the value  1 indexes the attribute.

For information about setting the searchFlags attribute, see the Microsoft Platform SDK link on the Web Resources page at https://windows.microsoft.com/windows2000/reskit/webresources .

Suppressing First/Last and Last/First Functionality

By default, Active Directory is configured to expand the ANR filter to evaluate the positions of two portions of a string that contains an embedded space. In the case of the sn and givenName attributes, the evaluation also includes checking whether the portion of the string that precedes the embedded space comes before or after the portion of the string that follows the space. If it comes before the portion of the string that follows the space, it is first/last functionality; if it comes after the portion of the string that follows the space, it is last/first functionality.

The DSHeuristics attribute on the Directory Service object (cn=Directory Service,cn=Windows NT,cn=Services,cn=Configuration,dc= ForestRootDomain ) contains a string value that governs the use of first/last and last/first functionality in the first two character positions. The default value of DSHeuristics is  00 , which indicates that both functions are enabled. (For all positions, "0" means "perform the default behavior.") The first character in the string governs first/last functionality; the second character governs last/first functionality.

You can modify the first two characters of the string to suppress either one or both functionalities as follows:

10 = Suppress first/last functionality. (This can also be written "1" or "10000" because both mean that only the first character's behavior must be nondefault.)

01 = Suppress last/first functionality.

11 = Suppress last/first and first/last functionality.