How does an LDAP referral reach a client as a result code, and how does a SearchResultReference differ from it?

middleshould knowfreq 42%

answer

two ways to say not mine
one stops, one continues
referral (10) rides on the result
a reference sits among the entries
success can still be incomplete

basics

~20 s

An LDAP referral arrives as resultCode referral (10) on the operation's own result: the server did the operation nowhere and hands back one or more LDAP URLs. A SearchResultReference arrives mid-search, alongside real entries, saying part of the subtree continues elsewhere.

solid answer

~50 s

Both say the same thing — the content you asked for is not mine — but they arrive at different moments and mean different things about what you already have. referral (10) is a resultCode in the operation's LDAPResult: nothing was performed, and the optional referral field carries Referral, one or more LDAP URLs naming servers that may hold the entry; matchedDN gives the deepest prefix of your base DN the server does hold. A SearchResultReference is a separate message inside a search response, interleaved with SearchResultEntry messages: the server searched what it holds, returned those entries, and is telling you that a branch of the subtree continues on another server. The search still ends with SearchResultDone, which may be success (0) even though the result is incomplete. Chaining is the alternative: the server follows the reference itself and returns one merged result.

Both say the same thing — the content you asked for is not mine — but they arrive at different moments and mean different things about what you already have. `referral (10)` is a resultCode in the operation's `LDAPResult`: nothing was performed, and the optional `referral` field carries `Referral`, one or more LDAP URLs naming servers that may hold the entry; `matchedDN` gives the deepest prefix of your base DN the server does hold. A `SearchResultReference` is a separate message inside a search response, interleaved with `SearchResultEntry` messages: the server searched what it holds, returned those entries, and is telling you that a branch of the subtree continues on another server. The search still ends with `SearchResultDone`, which may be `success (0)` even though the result is incomplete. Chaining is the alternative: the server follows the reference itself and returns one merged result.

code

asn1 · 12 lines

asn1

Referral ::= SEQUENCE SIZE (1..MAX) OF uri URI

LDAPResult ::= SEQUENCE {
     resultCode         ENUMERATED {
          success              (0),
          -- ...
          referral             (10),
          -- ...
          loopDetect           (54) },
     matchedDN          LDAPDN,
     diagnosticMessage  LDAPString,
     referral           [3] Referral OPTIONAL }

go deeper

for a junior

Recall that a directory server may hold only part of the tree and can point you at another server instead of answering. Know that a pointer is not the data.

for a middle

Explain that referral (10) means nothing was performed while a SearchResultReference arrives among real entries, and that the search can still end in success while being incomplete.

for a senior

Demonstrate the production failure: a short roster with no error because references were dropped, or fewer attributes after a chased referral because the new connection was never bound.

for a principal

Decide estate-wide whether clients chase references or servers chain, and own the consequence: a client-visible hop you can time out, or a hidden one that shows up as your own server being slow.

Two ways a directory server says "not mine"

A directory tree is often split across servers. The shipping line's shore office holds ou=crew,dc=example,dc=com, a manning agency holds ou=contractors,dc=example,dc=com, and no single server holds the whole tree. LDAP has two distinct ways for a server to tell a client that the content it wants lives somewhere else, and confusing them is one of the reliable ways to write a client that silently loses entries.

referral (10): the operation happened nowhere

Every LDAP operation ends with an LDAPResult. When the server cannot or will not perform the operation but knows where it could be performed, the resultCode is referral (10) and the optional referral field carries a Referral: one or more LDAP URLs.

matchedDN is filled in with the deepest existing prefix of the DN you named, which tells you how far down the tree this server actually goes.
Nothing was performed. There are no entries in the response and no partial work to merge.
The URLs use the ldap scheme and name a server and usually a DN. The client picks one, opens a new connection to it, and repeats the operation.
The new connection is a new connection: its authentication state is its own, set by its own LDAP Bind operation. Nothing carries over, so a client that followed a referral without binding again is suddenly reading as an unauthenticated caller and may see far less.

SearchResultReference: the search is continuing elsewhere

A search response is a sequence of messages. Most are SearchResultEntry. A SearchResultReference may be interleaved among them, and it means something narrower: the server searched the part of the subtree it holds and returned those entries, and one branch below your base continues on another server.

The entries you already received are real and complete for this server's share of the tree.
The search still terminates with SearchResultDone, and that result may be success (0). A successful search can therefore be an incomplete answer, which is the trap: a client that ignores references reports a short roster and no error.
Following a reference is a fresh search, on a fresh connection, with its own bind and its own limits.

Chaining: the server follows it for you

Instead of handing the URL back, a server may chain: contact the other server itself, perform the operation there, and return one result to the client. The client sees a single, complete answer and never learns a second server exists.

The cost is exactly what is hidden. The client's time limit now covers two servers and a network hop it cannot see, and a slow or unreachable second server looks to the client like a slow first server. Because chaining can cascade, servers guard against a cycle of hops with loopDetect (54); client-side chasing needs its own hop budget for the same reason.

Side by side

	`referral (10)`	`SearchResultReference`	Chaining
Where it appears	the operation's `LDAPResult`	among the search's messages	nowhere: it is invisible
Work already done	none	entries for this server returned	all of it
Who makes the next hop	the client	the client	the server
Failure mode if ignored	operation obviously fails	silently short result	hidden latency
Authentication on the hop	new connection, new bind	new connection, new bind	the server's own

What this looks like when it goes wrong

The classic incident is not an error at all. An application lists the crew for a vessel, gets success (0) and nineteen entries, and prints a roster. The twentieth seafarer's entry sits under a branch the shore server does not hold; a SearchResultReference named it, the client library discarded unknown message types, and nobody saw a failure. The second classic is the referral followed without a bind, where the search succeeds and returns fewer attributes than before, because the new connection is reading anonymously.

The operational rule that falls out of this: a client must decide explicitly whether it chases references, and if it does not, it must treat their presence as an incomplete result rather than as noise.

## Two ways a directory server says "not mine" A directory tree is often split across servers. The shipping line's shore office holds `ou=crew,dc=example,dc=com`, a manning agency holds `ou=contractors,dc=example,dc=com`, and no single server holds the whole tree. LDAP has two distinct ways for a server to tell a client that the content it wants lives somewhere else, and confusing them is one of the reliable ways to write a client that silently loses entries. ## referral (10): the operation happened nowhere Every LDAP operation ends with an `LDAPResult`. When the server cannot or will not perform the operation but knows where it could be performed, the `resultCode` is `referral (10)` and the optional `referral` field carries a `Referral`: **one or more** LDAP URLs. - `matchedDN` is filled in with the deepest existing prefix of the DN you named, which tells you how far down the tree this server actually goes. - Nothing was performed. There are no entries in the response and no partial work to merge. - The URLs use the `ldap` scheme and name a server and usually a DN. The client picks one, opens a new connection to it, and repeats the operation. - The new connection is a new connection: **its authentication state is its own**, set by its own LDAP Bind operation. Nothing carries over, so a client that followed a referral without binding again is suddenly reading as an unauthenticated caller and may see far less. ## SearchResultReference: the search is continuing elsewhere A search response is a sequence of messages. Most are `SearchResultEntry`. A `SearchResultReference` may be interleaved among them, and it means something narrower: the server searched the part of the subtree it holds and returned those entries, and one branch below your base continues on another server. - The entries you already received are real and complete for this server's share of the tree. - The search still terminates with `SearchResultDone`, and that result may be `success (0)`. **A successful search can therefore be an incomplete answer**, which is the trap: a client that ignores references reports a short roster and no error. - Following a reference is a fresh search, on a fresh connection, with its own bind and its own limits. ## Chaining: the server follows it for you Instead of handing the URL back, a server may **chain**: contact the other server itself, perform the operation there, and return one result to the client. The client sees a single, complete answer and never learns a second server exists. The cost is exactly what is hidden. The client's time limit now covers two servers and a network hop it cannot see, and a slow or unreachable second server looks to the client like a slow first server. Because chaining can cascade, servers guard against a cycle of hops with `loopDetect (54)`; client-side chasing needs its own hop budget for the same reason. ## Side by side | | `referral (10)` | `SearchResultReference` | Chaining | |---|---|---|---| | Where it appears | the operation's `LDAPResult` | among the search's messages | nowhere: it is invisible | | Work already done | none | entries for this server returned | all of it | | Who makes the next hop | the client | the client | the server | | Failure mode if ignored | operation obviously fails | silently short result | hidden latency | | Authentication on the hop | new connection, new bind | new connection, new bind | the server's own | ## What this looks like when it goes wrong The classic incident is not an error at all. An application lists the crew for a vessel, gets `success (0)` and nineteen entries, and prints a roster. The twentieth seafarer's entry sits under a branch the shore server does not hold; a `SearchResultReference` named it, the client library discarded unknown message types, and nobody saw a failure. The second classic is the referral followed without a bind, where the search succeeds and returns fewer attributes than before, because the new connection is reading anonymously. The operational rule that falls out of this: a client must decide explicitly whether it chases references, and if it does not, it must treat their presence as an incomplete result rather than as noise.

A search returns success (0) and the caller still has an incomplete answer — how?
The response carried one or more `SearchResultReference` messages. The server returned every entry it holds under the base and told the client that a branch continues elsewhere; that is not an error, so `SearchResultDone` is `success (0)`. A client that ignores reference messages reports a short result with no failure to notice.
What does matchedDN add to a referral response?
It names the deepest prefix of the requested DN that this server actually holds. It tells the client how far down the tree this server's naming context reaches, which distinguishes "I hold nothing near this" from "I hold the parent but not this child", and it is useful even when the client will not chase the referral.
Why does loopDetect (54) exist?
Because a chaining server may contact a server that chains back, directly or around a cycle. `loopDetect (54)` is the result code a server returns when it detects that the operation has come round to it again, ending the cycle with a diagnosable answer rather than a hang. Client-side chasing needs its own hop limit for the same reason.

A referral is a switchboard that reads you another number and hangs up: you dial it yourself, on your own line, and you have to identify yourself again at the other end. Chaining is the switchboard placing the call for you and staying on the line — one conversation from your side, with the extra delay buried inside it.

saying these in an interview costs you the question

Treats a SearchResultReference as an error that aborts the search
Thinks a referral response also contains the entries themselves
Assumes credentials carry over to the server named in the referral
Says a search returning references cannot report success
Believes chaining removes the extra hop rather than hiding it
Confuses an LDAP referral with a Kerberos referral to another realm

How does an LDAP referral reach a client as a result code, and how does a SearchResultReference differ from it?

§ answer

basics

solid answer

code

§ go deeper

▾level notes4 levels

▾deep dive~4 min

Two ways a directory server says "not mine"

referral (10): the operation happened nowhere

SearchResultReference: the search is continuing elsewhere

Chaining: the server follows it for you

Side by side

What this looks like when it goes wrong

▾common follow-ups3 questions

▾analogy~20 s

▾red flags6 flags

Two ways a directory server says "not mine"

referral (10): the operation happened nowhere

SearchResultReference: the search is continuing elsewhere

Chaining: the server follows it for you

Side by side

What this looks like when it goes wrong

answer

go deeper