Understanding ADAM LDAP referrals

Updated: August 22, 2005

Applies To: Windows Server 2003 R2

ADAM LDAP referrals

In accordance with RFC 2251, Active Directory Application Mode (ADAM) supports the use of referrals. With referrals you can use ADAM to direct LDAP clients to a more appropriate location in response to a query from the client. Also in accordance with RFC 2251, ADAM can return referrals in response to any LDAP operation request, except "unbind" and "abandon" requests, which have no responses. ADAM maintains referral data in crossRef objects that are stored in the partitions container of the configuration directory partition.

ADAM creates and maintains crossRef objects for all directory partitions in the configuration set, including the configuration and schema partitions. These crossRef objects are used to generate referrals in response to queries that request data about objects that exist in the configuration set but that are not contained in the ADAM instance handling the request.

At a minimum, at least one Uniform Resource Locator (URL) must be present in the referral. When possible, ADAM returns at least three referrals, to provide referral redundancy to clients in distributed environments. A referral is not returned for a singleLevel or wholeSubtree search in which the search scope spans multiple naming contexts and several different servers must be contacted to complete the operation. Instead, continuation references are returned.

If a crossRef object with a matching directory partition exists, ADAM uses it for referrals. However, if a crossRef object does not exist, but the queried namespace uses DNS-style (DC=) naming, ADAM constructs a DNS name to be used as a referral. If the queried namespace does not use DNS-style naming, a superior reference is used, if one exists. A superior reference can be configured by setting the superiorDnsRoot attribute on the configuration partition crossRef object. If a superior reference is not configured (it is not configured by default), an operational error is returned.

Generating referrals from a crossRef object

If the dNSRoot attribute has been set on the crossRef object (dNSRoot is not set by default), ADAM returns the DNS name as the referral for the queried namespace. (By default, the dNSRoot attribute is set to NULL.) Then, the client can chase the referral through registered DNS records for each host that contains the queried namespace.

If the dNSRoot attribute is NULL, the referral is generated based on other information about the crossRef, as follows:

ADAM refers to the msDS-NC-Replica-Locations attribute to find the NTDS Settings objects representing the instances hosting this partition (for example: CN=NTDS Settings,CN=Machine1$instance1,CN=Servers,CN=Default-First-Site-Name,CN=Sites,CN=Configuration,CN={<GUID>}). If more than three ADAM instances host the directory partition, a randomly selected set of three instances is chosen.

From the NTDS Settings object (the authoritative source within the directory for communications port information), ADAM retrieves the msDS-PortLDAP attribute for the communications port.

From the parent (Server Object), ADAM retrieves the dNSHostName attribute (instance1.machine1.example.com). dNSHostName is the authoritative source for the server host name, and it can either be a DNS host name or a host Internet Protocol (IP) address. If the server name changes, this object can be relied on to have the updated information.

ADAM then constructs the referral based on the server and communications port information. ADAM returns multiple referrals for each request to ensure that the client can pursue the request, even if one or more hosts represented in the referrals cannot be reached. ADAM selects a random number of locations (three by default) and continues to use those defaults for five minutes, after which another three hosts are selected. Both the number of hosts and number of minutes are configurable. If the number of hosts specified is greater than the actual number of instances holding the directory partition, all of the hosts are returned as referrals, and they will continue to be used indefinitely. This information is kept in the crossref cache, and it is refreshed anytime the crossref cache is rebuilt. The crossref cache is automatically rebuilt when msds-nc-replica-locations changes, that is, when an ADAM instance is added or removed.

Note

You can modify the values in the following table on the msDS-Other-Settings attribute of the directory service object, or on a crossRef object, to configure the referral behavior of an ADAM instance.

Values that you set on a crossRef object take precedence over any values that you set on the directory service object.

Generating referrals without crossRef objects

If a crossRef does not exist for the search base, ADAM determines the DNS name if the distinguished name that is presented in the request uses DNS-style (DC=) syntax. Otherwise, ADAM uses the supref attribute of the configuration directory partition to generate a referral to the Superior Referral, if one is configured. This attribute is NULL by default, and it must be configured explicitly. Otherwise, no referrals are generated.