LDAP Referrals

On this page

What Are LDAP Referrals?

In LDAP, a referral is a protocol mechanism by which an LDAP server informs a client that the requested directory information is not stored locally, but may be available elsewhere. Instead of returning the data (or a hard error), the server responds with one or more LDAP URLs indicating alternate directory locations—potentially on different servers or under other naming contexts—where the operation might succeed. Referrals are an explicit indication that the server is not authoritative for the requested portion of the directory.

Typical scenarios triggering referrals include:

A client requests a distinguished name (DN) that lies outside the server's managed subtree or partition.
A search operation traverses a naming boundary, and the next segment is hosted elsewhere.
The server is configured to delegate or partition parts of the Directory Information Tree (DIT) to other LDAP servers.

Why Do Referrals Matter?

Referrals are essential in distributed LDAP environments, where the DIT is partitioned across multiple servers for scalability, operational boundaries, or administrative autonomy. Rather than requiring every server to hold a global directory replica, LDAP referrals let clients navigate seamlessly across partitions. This approach allows for clean delegation of authority, cost-effective scaling, and administrative divisions—common in large enterprises, global organizations, or multi-tenant directory deployments.

With referrals, changes to directory topology (such as moving a subtree to a different server) can be surfaced to clients as pointer responses, enabling dynamic and modular architectures. However, this also introduces complexities: clients must know how to handle referrals; deployments need to carefully design referral topologies to avoid loops or dead-ends.

How Do LDAP Referrals Work?

When a server receives an operation targeting a DN or search base it does not manage, it constructs a referral response. Per RFC 4511, this response includes the LDAP result code referral (10) and one or more alternative LDAP URLs in the referral field of the protocol message. The server's responsibility ends with issuing this referral—no further chaining or client-side operation is performed by the server.

From the moment the client receives a referral, it must decide if and how to follow—"chase"—the pointers. The client parses the URLs, determines which server(s) or naming context(s) are referenced, and, if it chooses to proceed, opens a new connection or issues a new request at the referred location. The original operation is then retried with parameters potentially tweaked per the referral's LDAP URL fields.

The division of labor is strict: LDAPv3 requires referral chasing to be performed by the client, not the server, except in vendor-specific chaining or proxy scenarios.

LDAP URL Format in Referrals

LDAP referrals are always encoded as LDAP URLs, as specified in RFC 4516. The canonical form is:

text

ldap[s]://host:port/<base_dn>?[attributes]?[scope]?[filter]

Key elements:

Scheme: ldap:// or ldaps:// indicates standard or TLS-protected protocol.
Host: Target server hostname or IP address.
Port: Optional; defaults to 389 for LDAP, 636 for LDAPS.
Base DN: Distinguished name of the entry or subtree at the remote location.
Attributes, Scope, Filter: Optional search directives—rarely present in simple partitioning, but may be populated in continuation references.

When multiple URLs are included in a referral, each represents an equivalent alternative for the client; the client may select any for continued operation.

Referral Chasing and Client Behavior

Referral chasing describes the client-side logic for processing referrals. Upon receiving a referral, the client:

Inspects the LDAP URLs provided.
Chooses an appropriate URL (potentially based on URL features, trust, or network affinity).
Repeats the original operation at the referred server or naming context.
Handles any additional referrals if the chase crosses further boundaries.

Whether clients chase referrals automatically, partially, or not at all is an implementation detail—and a critical configuration point. Automatic referral chasing simplifies some scenarios but brings security and audit challenges: users may be unknowingly redirected, credentials could be sent to unintended servers, or operations may cross security boundaries without visibility. Disabling or strictly controlling referral chasing is often recommended in security-conscious deployments.

Misconceptions abound: the LDAP server does not chase referrals or follow-the-pointer for the client unless explicitly designed as a chaining proxy. LDAPv3 explicitly leaves referral chasing as a client-side (application or SDK) responsibility.

Continuation References in Searches

Not all referrals are simply redirect responses. During subtree searches, the server may discover that part of the requested search base lies in a different partition or server. In these cases, the server includes a continuation reference—a form of referral—indicating where to continue the search. Continuation references carry enough context (base DN, scope, filter) for the client to issue the same search parameters at the targeted server.

For example, if a subtree search is initiated at the root DN but an organizational unit has been delegated, the server returns partial results and a continuation reference so the client can continue searching in the delegated partition. This is key for correct, seamless search coverage in distributed directories.

Referral Objects and Subordinate References

Beyond dynamic referral responses, LDAP can store referral information directly in the directory as referral objects. According to RFC 3296, a referral object uses the referral objectClass and contains one or more ref attributes populated with LDAP URLs. These entries act as named subordinate references, essentially serving as persistent 'pointers' within the DIT that inform servers (and clients) about partitioning.

Such referral objects enable server implementations to consult the DIT schema itself when deciding where referrals apply. They also provide a means to manage and audit directory partition boundaries.

Referrals vs Aliases

Although sometimes conflated, aliases and referrals play fundamentally different roles:

Alias: An LDAP alias is a directory entry that acts as a pointer to another entry within the same directory (usually via an aliasedObjectName attribute). When a request references an alias, the server internally dereferences it and operates as if the target entry was requested. Alias resolution is entirely server-side and opaque to the client.
Referral: A referral is a server response telling the client to continue the operation at another server or namespace, communicated via LDAP URLs. The client, not the server, must handle the transition.

Aliases are suitable for within-directory indirection. Referrals are required when delegation crosses server or administrative boundaries.

Referrals in Active Directory

Active Directory (AD) heavily leverages LDAP referrals for directory partitioning and domain/forest navigation.

CrossRef objects in the AD configuration partition define the location and namespace for each domain and application partition. When an operation crosses a domain boundary or targets another partition, AD looks up the relevant CrossRef object to generate an appropriate referral.
Cross-domain and cross-forest referrals: AD returns referrals when a client attempts an operation on a DN outside the local domain or forest. The referral typically points to domain controllers or Global Catalog servers for the target domain or application partition, using LDAP URLs.
Binding requirements and errors: If a client is not authenticated or authorized to chase referrals—or if the referred location requires different credentials—the client may encounter errors such as unwillingToPerform or unavailable.

Practically, AD environments rely on referrals for seamless client navigation among domains, but this introduces operational complexity: firewalls, trust relationships, and client capabilities must all be configured to support correct referral chasing.

Common Issues, Security Considerations, and Troubleshooting

Common Issues

Misconfigured or stale referrals: If a referral points to a nonexistent or unreachable server, clients fail with errors or hang on connection attempts.
Referral loops: Poorly designed referral chains can result in infinite loops, leading to timeouts or stack exhaustion on clients.
Partial search results: Clients that do not chase continuation references will see incomplete search results for subtree queries spanning multiple partitions.
Credentials mishandling: Automatic referral chasing can lead to credentials being sent to unintended servers if not carefully controlled.

Security Considerations

Untrusted referrals: Accepting referrals to arbitrary, untrusted servers can enable man-in-the-middle attacks, credential interception, or data exfiltration.
Privilege boundaries: Referral chasing can inadvertently cross administrative realms, violating intended access control boundaries.
Mitigation: It's recommended to disable or limit automatic referral chasing where security matters, and to audit referral targets for correctness and trustworthiness.

Troubleshooting Patterns

Recognizing referral errors: LDAP result code referral (10) or client error logs mentioning 'referral received' and a list of LDAP URLs.
Debugging loops: Examine referral chains for cycles using directory management tools or schema inspection.
Addressing partial results: Ensure clients and SDKs are configured to handle continuation references as required, or structure searches to avoid crossing unmanaged boundaries.
Verifying AD CrossRef configuration: Misconfigurations often stem from incorrect or missing CrossRef objects, which can be audited in the AD configuration partition.

LDAP referrals are powerful tools for directory scaling and modularization. However, they demand careful design, explicit client handling, and continuous operational and security review to ensure robust, trustworthy integrations—especially in critical applications and enterprise identity infrastructures.

Sources