Json2Ldap :: Specification

JSON-RPC web service for LDAP directory access

The Json2Ldap is a JSON-RPC 2.0 gateway / proxy service for accessing directories over the web. It accepts requests over HTTP(S) POST.

LDAP v3 compatibility

Json2Ldap is compatible with directories supporting the current version 3 of the Lightweight Directory Access Protocol (LDAP).

Popular proprietary directory servers:

Active Directory from Microsoft
eDirectory from Novell
Tivoli Directory Server from IBM
Oracle Internet Directory from Oracle Corporation

Open source directory servers:

OpenLDAP, the first influential open source implementation
OpenDJ, originally from Sun and written in Java
389 Directory Server, a RedHat/Fedora project
Apache DS, project of the Apache Software Foundation

Web API

Json2Ldap handles JSON remote procedure call (RPC) requests for all standard directory operations as well as requests for a few useful LDAP extensions. See the Json2Ldap web API.

Directory connection	Directory authentication	Directory read and search
`ldap.connect` `ldap.isConnected` `ldap.close`	`ldap.simpleBind` `ldap.anonymousBind` `ldap.plainBind` `ldap.digestMD5Bind`	`ldap.getEntry` `ldap.search` `ldap.compare` `ldap.getRootDSE`
Directory write operations	Extended directory operations	Utility functions
`ldap.add` `ldap.add (LDIF)` `ldap.delete` `ldap.deleteTree` `ldap.modify` `ldap.modify (multiple)` `ldap.modify (LDIF)` `ldap.modifyDN`	`ldap.ext.passwordModify` `ldap.ext.whoAmI`	`ldap.util.isValidDN` `ldap.util.normalizeDN` `ldap.util.compareDNs` `ldap.util.isValidFilter` `ldap.util.encodeFilterValue`
Directory schema information		SRP-6a authentication
`ldap.schema.getObjectClass` `ldap.schema.getObjectClasses` `ldap.schema.getAttributeType` `ldap.schema.getAttributeTypes` `ldap.schema.getMatchingRule` `ldap.schema.getMatchingRules` `ldap.schema.getMatchingRuleUse` `ldap.schema.getMatchingRuleUses` `ldap.schema.getSyntax` `ldap.schema.getSyntaxes`		`x.srp6.getSettings` `x.srp6.bind (step 1)` `x.srp6.bind (step 2)` `x.srp6.setVerifier`
		Web service information
		`ws.getName` `ws.getVersion` `ws.getTime`

Deployment

Json2Ldap is packaged as a standard web application archive (WAR) ready for immediate deployment in a Java servlet container, such as the popular open source Apache Tomcat server.

Configuration

Json2Ldap allows for comprehensive configuration by a set of parameters specified in the standard WEB-INF/web.xml web app descriptor file. See the Json2Ldap configuration for details.

Client interface	LDAP connections
`json2ldap.clients.requireAuthentication` `json2ldap.clients.requireSecureAccess` `json2ldap.clients.denyWriteRequests` `json2ldap.clients.denyReadRequests` `json2ldap.clients.denyBindRequests` `json2ldap.clients.denyPasswordModifyRequests` `json2ldap.clients.denyWhoAmIRequests` `json2ldap.clients.connectionQuotaPerIP` `json2ldap.clients.connectionQuotaPerUser` `json2ldap.clients.maxIdleTime` `json2ldap.clients.maxConnectionTime` `json2ldap.clients.responseContentType` `json2ldap.clients.reportRequestProcTime`	`json2ldap.ldap.allowedServers` `json2ldap.ldap.requireSecureAccess` `json2ldap.ldap.autoReconnect`
	Default LDAP connection
	`json2ldap.defaultConnection.enable` `json2ldap.defaultConnection.server` `json2ldap.defaultConnection.timeout` `json2ldap.defaultConnection.security` `json2ldap.defaultConnection.trustSelfSignedCerts`
Custom trust / key store for TLS/SSL LDAP	SRP-6a authentication
`json2ldap.ldap.customTrustStore.enable` `json2ldap.ldap.customTrustStore.file` `json2ldap.ldap.customTrustStore.type` `json2ldap.ldap.customTrustStore.password` `json2ldap.ldap.customKeyStore.enable` `json2ldap.ldap.customKeyStore.file` `json2ldap.ldap.customKeyStore.type` `json2ldap.ldap.customKeyStore.password`	`json2ldap.x.srp6.enable` `json2ldap.x.srp6.dn` `json2ldap.x.srp6.password` `json2ldap.x.srp6.attribute` `json2ldap.x.srp6.primeSize` `json2ldap.x.srp6.saltSize` `json2ldap.x.srp6.hashAlgorithm` `json2ldap.x.srp6.timeout`
In-memory directory server	Cross-Origin Resource Sharing (CORS)
`inMemoryDirectoryServer.enable` `inMemoryDirectoryServer.port` `inMemoryDirectoryServer.schema` `inMemoryDirectoryServer.baseDN` `inMemoryDirectoryServer.content`	`cors.allowGenericHttpRequests` `cors.allowOrigin` `cors.supportedMethods` `cors.supportedHeaders` `cors.exposedHeaders` `cors.supportsCredentials` `cors.maxAge`
Logging
`json2ldap.log4j.configurationFile`

Logging

Json2Ldap uses the popular log4j utility. Here are the event types that can be selectively logged:

On a HTTP request: method name, client IP, CORS origin (if applicable).
On a JSON-RPC 2.0 request: method name, LDAP connection identifier (CID) (if applicable), response status (success or error code).
The creation, termination and expiration of LDAP connections.
Internal Json2Ldap exceptions.

Logging is configured through the WEB-INF/log4j.properties file.

System requirements and dependencies

Json2Ldap requires a web server conforming to the Java servlet specification, such as Apache Tomcat or Jetty:

Java 1.6+
Java servlet API 2.5+

All package dependencies are included in the Json2Ldap WAR file for convenience.

Change log

version 1.0 (2010-04-28)
- First official and stable release.
version 1.1 (2010-05-22)
- Factors out JSON-RPC 2.0 request dispatching framework in separate generic package.
version 1.2 (2010-06-21)
- New categorisation of the configuration parameters.
- Adds configuration parameter to set a connection quota per bound DN.
- Adds configuration parameter to limit total LDAP connection time.
- Adds configuration parameter to enable automatic LDAP reconnect.
- Adds configuration parameter to deny "Password Modify" request relay.
- Adds configuration parameter to deny "Who am I?" request relay.
- Refactors the LDAP connection manager and storage.
- Updates UnboundID SDK JAR to 1.1.4.
version 1.3 (2010-06-23)
- Simplifies the API by removing the ldap.presetBind command.
version 1.3.1 (2010-06-29)
- Fixes two DTD compatibility errors in WEB-INF/web.xml.
- Updates JsonRpc2-Client tool to 1.3.
version 1.4 (2010-08-15)
- Merges ldap.secureConnect and ldap.presetConnect requests into ldap.connect.
- New ResultFormat class assists parsing of output type params.
- New Json2LdapConfigurationException class reports bad init parameters on startup.
- Updates JsonRpc2-Base JAR to 1.9.3.
version 1.5 (2010-08-30)
- ldap.search request allows to specify retrieval of all, none or operational attributes only.
- Include DNs in ldap.search output formatted as JSON.
- Updates JsonRpc2-Base JAR to 1.9.4.
version 1.5.1 (2010-09-01)
- Updates UnboundID SDK JAR to 1.1.5.
version 1.5.2 (2010-09-02)
- Includes new fields "timeLimitExceeded" and "sizeLimitExceeded" in ldap.search JSON results to nofity users of partial result sets.
version 1.5.3 (2010-09-05)
- Adds support for server-side sorting (RFC 2891) in ldap.search.
- Includes explicit "DN" property in ldap.getEntry and ldap.search result entries.
- Reverts to strict handling of time|size limit exceeded errors in ldap.search.
version 1.5.4 (2010-09-09)
- Updates JsonRpc2-Base JAR to 1.10.
version 1.6 (2010-10-10)
- Connection identifiers (CIDs) now represented by standard UUIDs.
- ldap.connect returns object with CID string as member instead of simple string.
- ldap.simpleBind and ldap.anonymousBind return empty object instead of null.
- Adds configuration parameter to specify response content type.
- Includes Cross-Origin Resource Sharing (CORS) Filter 1.1.
- Updates UnboundID SDK JAR to 1.1.6.
- Updates JsonRpc2-Base JAR to 1.11.
- Updates JsonRpc2-Proc JAR to 1.1.
- Updates Property Util JAR to 1.2.
- Updates JsonRpc2 Shell to 1.4.
version 1.7 (2010-11-18)
- ldap.search adds support for the simple paged results control (RFC 2696).
- ldap.modifyDN parameter deleteOldRDN now defaults to false.
- More detailed error messages for extended LDAP operations.
- Fixes bug in ldap.modify multi mods processing.
- Fixes bug in ldap.modify using LDIF.
- Updates UnboundID SDK JAR to 2.0.0.
- Updates Property Util JAR to 1.3.
version 1.7.1 (2010-11-23)
- Switches from JsonRpc-Proc 1.1 to JsonRpc2-Server 1.2 JAR.
version 1.7.2 (2010-12-01)
- Minor change to the ldap.search API - the LDIF formatted result allows inclusion of referrals and pageCookie.
- Fixes bug in ldap.add for multivalued BASE-64 encoded attributes.
version 1.7.3 (2010-12-18)
- Fixes bug that prevented retrieval of generated passwords from password modify extended requests.
version 1.8 (2011-03-16)
- Adds utility request "ldap.util.isValidDN".
- Adds utility request "ldap.util.normalizeDN".
- Adds utility request "ldap.util.compareDNs".
- Adds utility request "ldap.util.encodeFilterValue".
- Improves clarity of JSON-RPC 2.0 request/response log messages.
- Updates UnboundID SDK JAR to 2.0.1.
- Updates Property Util JAR to 1.4.
- Updates Java Mail JAR to 1.4.4.
- Updates Apache Commons Lang JAR to 2.6.
- Updates JSON-RPC 2.0 Base JAR to 1.14.
- Updates JSON-RPC 2.0 Server JAR to 1.3.
- Updates JSON-RPC 2.0 Shell to 1.6.
version 1.8.1 (2011-04-14)
- Adds utility request "ldap.util.isValidFilter".
- Fixes bug that prevented the disabling of client IP quotas.
- Fixes bug that prevented the disabling of bind DN quotas.
- Updates UnboundID SDK JAR to 2.1.0.
version 1.9 (2011-05-16)
- Includes a simple in-memory LDAP server for testing and demonstration purposes.
version 1.9.1 (2011-05-20)
- Updates JSON-RPC 2.0 Base JAR to 1.16.
- Removes default admin account of the in-memory LDAP server and limits access to read and bind (authenticate) only.
- Adds groups to the sample demo.ldif file.
version 1.9.2 (2011-05-27)
- Removes stack trace logging on invalid JSON parse exception.
- Updates UnboundID SDK JAR to 2.2.0.
- Updates JSON-RPC 2.0 Shell to 1.7.
version 1.9.3 (2011-06-14)
- Thread-safe parsing of JSON-RPC 2.0 requests.
- Updates JSON-RPC 2.0 Base JAR to 1.17 (JSON Smart).
version 1.10 (2011-08-05)
- Adds configuration parameter to report request processing time by appending a non-standard "xProcTime" attribute to the JSON-RPC 2.0 responses.
- Updates JSON-RPC 2.0 Base JAR to 1.21.
- Updates JSON-RPC 2.0 Server JAR to 1.4.1.
- Updates JSON Smart to 1.0.9.
- Updates JSON-RPC 2.0 Shell to 1.9.
- Adds jpegPhoto attributes to the sample LDIF file.
version 2.0 (2011-10-10)
- Changes the API signatures of the ldap.connect and ldap.search.
- Adds a new ldap.plainSASLBind authentication request (RFC 4616).
- Introduces tracking of authenticated users based on their SASL authzId (RFC 4513, section 5.2.1.8). Bind DN tracking is obsoleted.
- Renames configuration parameter clients.connectionQuotaPerBindDN to clients.connectionQuotaPerAuthUser.
- Obsoletes JSON-RPC 2.0 error -1200 "Both bindDN and bindPassword must be set to request a simple bind (authentication)".
- Obsoletes JSON-RPC 2.0 error -1202 "DN and password must be set and non-empty" in favour of a more general -1200 "Invalid / incomplete bind (authentication) parameters".
- Renumbers JSON-RPC 2.0 error -1203 "Bind (authentication) required" to -1202.
- Adds JSON-RPC 2.0 error -1200 "Exhausted connection quota for this user".
- Adds JSON-RPC 2.0 error -2009 "Internal assert error".
- Improves error reporting on TLS/SSL ldap.connect exceptions.
- Switches to in-memory directory server (UnboundID) for JUnit testing.
- Updates JSON-RPC 2.0 Base JAR to 1.23.
- Updates JSON-RPC 2.0 Shell to 1.10.
- Improves documentation.
version 2.1 (2011-12-16)
- Adds support for digest MD5 bind (authentication) through the ldap.digestMD5Bind request.
- Adds support for Secure Remote Password (SRP-6a) bind (authentication) through the custom x.srp6.bind request.
- Renames request ldap.plainSASLBind to ldap.plainBind.
- Renames the json2ldap.clients.connectionQuotaPerAuthUser configuration parameter to json2ldap.clients.connectionQuotaPerUser.
- Adds dependency to Nimbus-SRP JAR 1.3.
- Updates UnboundID SDK JAR to 2.3.0.
- Updates JSON-RPC 2.0 Base JAR to 1.24.
- Updates Property Util JAR to 1.5.
- Updates CORS Filter JAR to 1.3.1.
- Updates JSON-RPC 2.0 Shell to 1.11.
version 2.2 (2011-12-27)
- Adds dependency to LDAP Util 1.0.
- Fixes purge timer thread leak.