LDAPWiki: SearchResultReference

Overview #

SearchResultReference provides a mechanism for returning information to DUA as part of a SearchRequest that indicates an alternate location in which the DUA may perform the search to locate additional matching entries. SearchResultReferences alternate locations will be specified in the form of LDAP URLs and are commonly referred to a LDAP Referral.

Continuation References in the Search Result #

If the DSA 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 LDAP 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 LDAP_NO_SUCH_OBJECT LDAP 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 LDAP Referral.

If the DUA wishes to progress the Search, it issues a new SearchRequest 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 (DUA) that follow search continuation references MUST ensure that they do not loop between servers (DSA). 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 Request operation described in applies only to a particular operation sent at the LDAP Message layer between a client and server. The client MUST individually issue Abandon Request for all subsequent Search operations.

A URI for a server implementing LDAP and accessible via TCP/IP (IPv4 or IPv6) RFC 793 & RFC 791 is written as an LDAP URL according to RFC 4516.

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 LDAP SearchFilter in the LDAP URL.
If the <filter> part of the LDAP URL is present, the client uses this filter in its next SearchRequest 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 "BaseObject".
It is RECOMMENDED that the LDAP Search Scope part be present to avoid ambiguity. In the absence of a LDAP Search Scope part, the LDAP Search Scope of the original SearchRequest is assumed.
Other aspects of the new SearchRequest may be the same as or different from the SearchRequest that generated the SearchResultReference.
The name of an unexplored subtree in a SearchResultReference need not be subordinate to the BaseDN.
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 RFC 3986.

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://hostb/OU=People,DC=Example,DC=NET??sub 
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://hostb/OU=People,DC=Example,DC=NET??base 
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 hosts, 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: