Overview #

A SearchResultReference provides a mechanism for returning information to clients as part of a SearchRequest that indicates an alternate location in which the client may perform the search to locate additional matching entries. The alternate locations will be specified in the form of LDAP URLs.

Continuation References in the Search Result #

If the server was able to locate the entry referred to by the baseObject but was unable or unwilling to search one or more non- local entries, the server may return one or more SearchResultReference messages, each containing a reference to another set of servers for continuing the operation. A server MUST NOT return any SearchResultReference messages if it has not located the baseObject and thus has not searched any entries. In this case, it would return a SearchResultDone containing either a referral or noSuchObject result code (depending on the server's knowledge of the entry named in the baseObject).

If a server holds a copy or partial copy of the subordinate naming context (Section 5 of RFC 4512, it may use the search filter to determine whether or not to return a SearchResultReference response. Otherwise, SearchResultReference responses are always returned when in scope.

The SearchResultReference is of the same data type as the Referral.

If the client wishes to progress the Search, it issues a new Search operation for each SearchResultReference that is returned. If multiple URIs are present, the client assumes that any supported URI may be used to progress the operation.

Clients that follow search continuation references MUST ensure that they do not loop between servers. They MUST NOT repeatedly contact the same server for the same request with the same parameters. Some clients use a counter that is incremented each time search result reference handling occurs for an operation, and these kinds of clients MUST be able to handle at least ten nested referrals while progressing the operation.

Note that the Abandon operation described in applies only to a particular operation sent at the LDAP message layer between a client and server. The client must individually abandon subsequent Search operations it wishes to.

A URI for a server implementing LDAP and accessible via TCP/IP (v4 or v6) RFC793 & RFC791 is written as an LDAP URL according to RFC4516.

SearchResultReference values that are LDAP URLs follow these rules:

  • The <dn> part of the LDAP URL MUST be present, with the new target object name. The client uses this name when following the reference.
  • Some servers (e.g., participating in distributed indexing) may provide a different filter in the LDAP URL.
  • If the <filter> part of the LDAP URL is present, the client uses this filter in its next request to progress this Search, and if it is not present the client uses the same filter as it used for that Search.
  • If the originating search scope was singleLevel, the <scope> part of the LDAP URL will be "base".
  • It is RECOMMENDED that the <scope> part be present to avoid ambiguity. In the absence of a <scope> part, the scope of the original Search request is assumed.
  • Other aspects of the new Search request may be the same as or different from the Search request that generated the SearchResultReference.
  • The name of an unexplored subtree in a SearchResultReference need not be subordinate to the base object.
  • Other kinds of URIs may be returned. The syntax and semantics of such URIs is left to future specifications. Clients may ignore URIs that they do not support.

UTF-8-encoded characters appearing in the string representation of a DN, search filter, or other fields of the referral value may not be legal for URIs (e.g., spaces) and MUST be escaped using the % method in RFC3986.

Examples #

For example, suppose the contacted server (hosta) holds the entry:
<DC=Example,DC=NET> and the entry <CN=Manager,DC=Example,DC=NET>.
It knows that both LDAP servers (hostb) and (hostc) hold <OU=People,DC=Example,DC=NET> (one is the master and the other server a shadow),
and that LDAP-capable server (hostd) holds the subtree <OU=Roles,DC=Example,DC=NET>.
If a wholeSubtree Search of <DC=Example,DC=NET> is requested to the contacted server, it may return the following:
SearchResultEntry for DC=Example,DC=NET 
SearchResultEntry for CN=Manager,DC=Example,DC=NET 

SearchResultReference { 
ldap://hostc/OU=People,DC=Example,DC=NET??sub } 
SearchResultReference { 
ldap://hostd/OU=Roles,DC=Example,DC=NET??sub } 
SearchResultDone (success) 
Client implementors should note that when following a SearchResultReference, additional SearchResultReference may be generated. Continuing the example, if the client contacted the server (hostb) and issued the Search request for the subtree
<OU=People,DC=Example,DC=NET>, the server might respond as follows:
SearchResultEntry for OU=People,DC=Example,DC=NET 

SearchResultReference { 
ldap://hoste/OU=Managers,OU=People,DC=Example,DC=NET??sub } 
SearchResultReference { 
ldap://hostf/OU=Consultants,OU=People,DC=Example,DC=NET??sub } 
SearchResultDone (success) 
Similarly, if a singleLevel Search of <DC=Example,DC=NET> is requested to the contacted server, it may return the following:
SearchResultEntry for CN=Manager,DC=Example,DC=NET 

SearchResultReference { 
ldap://hostc/OU=People,DC=Example,DC=NET??base } 
SearchResultReference { 
ldap://hostd/OU=Roles,DC=Example,DC=NET??base } 
SearchResultDone (success) 
If the contacted server does not hold the base object for the Search, but has knowledge of its possible location, then it may return a referral to the client. In this case, if the client requests a subtree Search of <DC=Example,DC=ORG> to hosta, the server returns a SearchResultDone containing a referral.
SearchResultDone (referral) { 
ldap://hostg/DC=Example,DC=ORG??sub } 

More Information #

There might be more information for this subject on one of the following: