Previous | Next | Trail Map | Tips for LDAP Users | Referrals

Referrals in the LDAP

This section provides an overview of LDAP referrals.

Comparison with Alias

In many ways, a referral is a generalization of an alias, which is discussed in the Miscellaneous (in the Tips for LDAP Users trail) lesson. An alias contains the DN of another object, whereas a referral contains one or more URLs of objects. The URLs are usually, but not necessarily, LDAP URLs. The LDAP URL contains the server's host/port and an object's DN. The host/port information can point to a directory server that differs from the one that returned the referral.

Whereas an alias is dereferenced and processed by the server, a referral is returned to the client, which is responsible for processing it.


Like an alias, a referral is useful for allowing an object to be identified by different names. Referrals can be used, for example, to accommodate the namespace changes and mergers that are inevitable as organizations evolve. In addition, they allow directory administrators to set up "search paths" for collecting results from multiple servers. They also can be used to deploy cache or read-only server replicas that return referrals for all update requests. Use of a read-only replica is among the many different load balancing strategies that can be implemented by using referrals.

Version 2 versus Version 3

The LDAP v2 provides limited support for referrals. An LDAP v2 server can be configured with a "default" referral so that if the information requested at the server does not exist, then the server will return a "partial result" error response that contains the referral URL. When the client receives this error, it will check whether the referral URL is present and use it instead of interpreting the response as a "partial result" error. The client uses the referral URL by contacting the server named in it to continue the requested operation.

The LDAP v3 explicitly supports referrals and allows servers to return them directly to the client. The server can return to the client a "referral" error response for any request that requires a response. This error response contains one or more URLs that are to be used to continue the operation. All of the URLs in the response are equivalent in that using any one should yield the correct result. The client should select one to continue the operation.

In addition, during an LDAP v3 "search" operation, a server can return a number of continuation references, which are of the same data type as a referral. The client is required to follow all continuation references. Like a referral, each continuation reference itself may contain a number of URLs assumed to be equivalent, and the client should use one of those URLs.

Unless a distinction is required, this lesson uses the term "referral" to mean the referral that is returned in either an error response or a continuation reference.

Previous | Next | Trail Map | Tips for LDAP Users | Referrals