Browse learn

LDAP Pagination

Learn how LDAP paged results let clients retrieve large result sets in manageable batches, including cookies, limits, and common implementation pitfalls.

Type
Concept
Level
Intermediate
Technologies
LDAP
On this page

What Is LDAP Pagination?

LDAP pagination, formally known as the Simple Paged Results control, is a protocol extension that allows clients to retrieve large search results from LDAP directories in discrete, manageable chunks called pages. Many directory queries—such as listing all users in a large organization—can produce thousands or even millions of results. Without pagination, these oversized responses can overwhelm server resources, clients, or network links, and often hit administrative or default server limits that cut off results unexpectedly.

Paging is essential when:

  • Directories are large or contain groups with thousands of entries.
  • The server enforces maximum response limits (e.g., Active Directory’s MaxPageSize, OpenLDAP’s sizelimit).
  • Clients need to show long lists in UI applications or batch processes.
  • Accuracy and completeness of results are critical (avoiding silent truncation).

A typical use case: An application needs to list all user distinguished names (DNs) from a corporate directory. The result set exceeds the server’s single-request limit, so paging is required to retrieve the entire listing reliably.

How LDAP Pagination Works: The Protocol Flow

The mechanism for LDAP pagination is defined in RFC 2696 as the Simple Paged Results control. The client initiates a search request with a control specifying the desired page size and, initially, an empty cookie. The protocol flow is strictly sequential:

  1. Initial Request: The client sends a search operation, attaching the Simple Paged Results control with a requested page size (e.g., 500 entries) and an empty cookie.
  2. First Response: The server returns up to the requested number of entries (or fewer, if limited by its configuration), plus a cookie in the response control.
  3. Continuation: To fetch the next page, the client repeats the search—using the same base DN, filter, and scope—with the cookie value provided by the previous response.
  4. Sequential Fetch: This request-response exchange continues, passing the latest cookie each time, until the server responds with an empty cookie, signaling that all results have been delivered.

Key details:

  • The cookie is an opaque value. Clients must not interpret or alter it; they simply pass it back to the server.
  • The client cannot skip ahead, jump to an arbitrary page, or request random-access slices. The protocol is strictly sequential.
  • Altering the base DN, search filter, or connection breaks the paging sequence; each change requires a new paged search session.

Understanding the Cookie: State, Stickiness, and Session Rules

The cookie is central to pagination in LDAP. It encodes server-side state about what has been retrieved and what remains. Its correct handling is crucial for reliable paging.

  • Opacity: The cookie’s content and meaning are defined entirely by the server implementation. Clients must not attempt to parse, construct, or modify it.
  • Lifecycle: On each page, the server issues a new cookie. The client returns the most recent cookie with the next search request. When the result set is exhausted, the server returns an empty (zero-length) cookie.
  • Session Stickiness: The paging cookie is valid only for the LDAP connection/session in which it was issued. If the client changes connections or the session times out, the cookie is invalid—continuing the sequence will fail.
  • Invariant Parameters: The search’s base DN, scope, and filter must be identical for every request in the paging sequence. Any change invalidates the cookie and disrupts the sequence.

Common mistakes:

  • Using a cookie across different connections or after a disconnect will result in errors (often "invalid cookie" or no results returned).
  • Attempting to change search parameters (e.g., requesting a different base DN or filter mid-sequence) renders the cookie useless.
  • Treating the cookie as a page number or offset index—unlike offset pagination in SQL or SCIM, the LDAP cookie is not client-interpretable.

Server-Side and Client-Side Constraints

LDAP paging is governed by several server-side and client-side constraints that developers must respect:

  • Server Page Size Limit: Servers enforce a maximum page size per request. For example, Active Directory defines MaxPageSize (often set at 1000 entries); OpenLDAP enforces sizelimit attributes. If a client requests more entries than the server permits in one page, the server typically returns an error, such as LDAP_SIZELIMIT_EXCEEDED.
  • Total Results Limit: Servers may also enforce a limit on the total number of entries returned to a bind identity (e.g., OpenLDAP's total sizelimit). Paging cannot overcome this cap—attempting to fetch more results is not possible.
  • Client Request Size: Clients should not assume their requested page size will be honored. Always request a size at or below known or documented server max.
  • Result Truncation and Errors: If a client ignores server size attributes, results may be truncated, and errors could be returned without all entries delivered.

Examples of constraints:

  • In Active Directory, setting a page size above MaxPageSize results in an immediate error and no results returned.
  • In OpenLDAP, both the size of individual pages and the total returned result set are capped per user, group, or IP.

Implementing Pagination in Practice

Major LDAP client libraries expose pagination as an extension or control, mirroring the protocol flow:

  • Java JNDI: Developers use the paged results control, specify the page size, and handle cookies directly—requesting new pages by sending the cookie from the previous response.
  • PHP: Until deprecated in PHP 8, the ldap_control_paged_result function enabled paged searches, requiring explicit management of the returned cookie between requests.

The common pattern across environments is:

  1. Enable or attach the paged results control with the desired page size.
  2. Submit a search request, process the results, and extract the returned cookie.
  3. Repeat the search with the new cookie until it becomes empty.
  4. Always use the same LDAP connection, base DN, and filter through the sequence.

Developers are responsible for:

  • Tracking the cookie precisely, passing it unmodified to each new request.
  • Handling error states if paging is interrupted or the connection drops.
  • Confirming that the target server supports the paged results control before relying on it.

Common Issues, Pitfalls, and Troubleshooting

Many integration failures with LDAP pagination trace to a short set of predictable mistakes:

  • Cookie Reuse After Session Loss: If the LDAP connection is reset or replaced between pages, the server-side state is lost and the cookie becomes invalid. Attempts to continue paging will fail—results may be incomplete, or errors will be returned.
  • Parameter Mismatch: Changing any of the base DN, scope, or filter between requests breaks the paging sequence.
  • Page Size Too Large: Requesting a page size larger than allowed by the server produces errors, often LDAP_SIZELIMIT_EXCEEDED or equivalent server-side limits.
  • Resource or Policy Limits: When a server-imposed size limit is hit (total max entries for a user, for example), paging cannot continue.
  • Silent Truncation: If the client ignores errors and continues, only part of the directory may be retrieved, with missing entries.

Troubleshooting steps:

  • Confirm that all paged requests use the same session, base, filter, and scope.
  • Check server logs for explicit errors or policy limit messages.
  • Use conservative page sizes and verify against documented server maximums.
  • Ensure the client is compatible with the server’s control support and handles cookies strictly as opaque values.

LDAP Pagination vs. Virtual List View: Key Differences

In addition to classic paged results, some servers support the Virtual List View (VLV) control for client-side result browsing. There are crucial differences:

  • Sequencing: Paged results (RFC 2696) provide sequential traversal only, no random access or offsetting.
  • Random Access: VLV aims to support jumping directly to a 'window' of entries, closer to true offset pagination (e.g., starting from entry 101).
  • Compatibility: VLV is not universally supported; mainline OpenLDAP, for example, does not implement VLV by default.
  • Use Cases: VLV is best for UIs showing potentially sorted, windowed results. RFC 2696 pagination is robust for sequential processing and is supported in all major directory servers.

Best Practices and Recommendations

Robust LDAP pagination depends on careful adherence to the protocol and awareness of environment specifics:

  • Always confirm paged control support before usage, as not all servers or schemas support it identically.
  • Request page sizes below or at the server maximum to avoid avoidable errors. When in doubt, start at conservative defaults (e.g., 500 entries) and adjust only if needed.
  • Maintain connection/session stickiness throughout the entire paging sequence. Do not open or reuse a new LDAP connection until the sequence completes.
  • Keep search parameters immutable for the duration of paging; changes require starting a new paged search.
  • Treat the cookie as completely opaque—do not attempt to parse, synthesize, or modify it.
  • Build error and restart logic, anticipating connection drops, session timeouts, and possible server limit errors.
  • Validate results and watch for silent truncation when testing across multiple directories or hybrid environments.

Further Reading and Authoritative Resources

For comprehensive protocol and implementation details, consult these standards and official documentation:

  • RFC 2696: LDAP Control Extension for Simple Paged Results Manipulation
  • Microsoft Learn: Paging Search Results
  • OpenLDAP Administrator’s Guide: Limits
  • Java Tutorials: Paged Results Control
  • Microsoft: LDAP Paged Search Control (MS-UPSLDAP)

Sources

Related resources