Json2Ldap now supports paged LDAP search results

Json2Ldap iconYesterday I got another update of Json2Ldap out, under version 1.7.

So what’s in it?

The major news is the added support for the LDAP extension (RFC 2696) for paged search results. Usage of search requests that return potentially thousands of matches is not uncommon, as some recent Json2Ldap applications have demonstrated. Directory servers, however, typically enforce a limit on the number of max. returned entries (typically ~ 1000), and this, together with the fact that large sets are more sensibly processed in chunks on the client side, make this a useful extension.

So how do you request a paged search with Json2Ldap?

This is done through the standard ldap.search JSON request, which now has two optional named parameters, namely pageSize and pageCookie.

To make a paged search request write your regular ldap.search JSON-RPC request, but also include a pageSize parameter that specifies the max. number of entries a page should have.

Here, an example request with a page size set to 50 entries:

{ "method"  : "ldap.search",
  "params"  : { "CID"      : "15002fb7-a830-413f-9445-858cf9a2cc6d",
                "baseDN"   : "ou=people,dc=example,dc=com",
		"scope"    : "SUB",
		"filter"   : "(objectClass=person)",
		"pageSize" : 50 },
  "id"      : 1,
  "jsonrpc" : "2.0" }

Then, when you get the Json2Ldap search response, check the value of the pageCookie result property. Note that this property is included only for paged searches, otherwise not!

{ "result"  : { "matches"    : [ ... ],
                "referrals"  : [ ... ],
                "pageCookie" : "AAAAAAAAAAw=" }
  "id"      : 1,
  "jsonrpc" : "2.0" }

If the pageCookie is an empty string, this indicates that there are no further pages and all matches are already retrieved.

Otherwise, the string represents a cookie (arbitrary BASE-64 encoded identifier generated by the LDAP server) which must be passed unmodified back to the directory server to retrieve the next page. This operation can be repeated until an empty pageCookie is returned, i.e. there are no more pages.

So, to retrieve the next page, create an identical search request, but this time also include the cookie string from the previous result page:

{ "method"  : "ldap.search",
  "params"  : { "CID"        : "15002fb7-a830-413f-9445-858cf9a2cc6d",
                "baseDN"     : "ou=people,dc=example,dc=com",
		"scope"      : "SUB",
		"filter"     : "(objectClass=person)",
		"pageSize"   : 50,
		"pageCookie" : "AAAAAAAAABw=" },
  "id"      : 1,
  "jsonrpc" : "2.0" }

I have written an article listing which directory servers support paged results. Most major servers have it. In future I may consider implementing the virtual list view (VLV) extension as well. It is somewhat more complicated, and interestingly, it hasn’t turned into an RFC (the last draft is from 2002).