Managing Json2Ldap connections
A few notes on using Json2Ldap’s web API for MS-AD / LDAP directory access:
The nature of LDAP connections
- LDAP connections are persistent and stateful.
- They run over TCP/IP. Once established, a connection remains open until explicitly closed by the client. The directory server may impose an idle time limit to purge LDAP connections that are no longer in use.
- LDAP connections are stateful. They are tied to a particular identity if the user has authenticated, else they are in an unauthenticated / anonymous state.
Mapping LDAP connections to Json2Ldap connection identifiers (CIDs)
When Json2Ldap serves an ldap.connect request from a web client, it creates an LDAP TCP/IP connection to the specified directory and returns a connection identifier (CID), or handle, for it.
{ "CID" : "979e71d8f0cf47d" }
The client should store the CID in a local variable so that it can refer to the connection in subsequent directory requests such as ldap.search or ldap.modify.
// Store CID from successful ldap.connect response
var cid = response.result.CID;
// The CID is a string like "979e71d8f0cf47d"
alert("CID: " + cid);
// Use CID as connection handle in directory request
var request = {};
request.method = "ldap.getEntry";
request.params = {};
request.params.CID = cid;
request.params.DN = "uid=alice,ou=people,dc=wonderland,dc=net";
request.attributes = ["cn mobile mail"];
request.id = "0001";
request.jsonrpc = "2.0";
// Send request to Json2Ldap URL via XHR
// ...
The LDAP connection is closed when the client makes an ldap.close request.
Imposing LDAP connection time limits
It is good practise to close an LDAP connection when it’s no longer in use to conserve the resources of the Json2Ldap web service and LDAP directory behind it. Otherwise the connection may theoretically remain open forever. Web clients may be sloppy in closing unused connections, so it makes sense to impose limits on LDAP connection lifespan and / or idle time.
Directory servers typically allow for such limits to be specified. You may also configure Json2Ldap to do that independently from the backend directory. This is done by the following configuration settings:
These settings will allow you to purge any unused connection if you have a web client that forgot to close it with ldap.close.
If a web client tries to access an expired LDAP connection it will get the following Json2Ldap error:
{ "code" : -1000,
"message" : "Invalid\/expired LDAP connection identifier (CID)"
}
A client can check of the status of a connection (active / inactive) with ldap.isConnected.
Optimising performance and resource usage
Establishing LDAP connections is not a cheap operation. You may improve performance and resource consumption of your directory application by reusing a CID across multiple operations and by closing the handle explicitly when it’s no longer in use.