Json2Ldap datasheet

JSON-RPC web service for LDAP directory access

The Json2Ldap is a JSON-RPC 2.0 gateway / proxy service for accessing LDAP directories over the web.

Supported LDAP operations and controls

Json2Ldap supports all core LDAP operations (RFC 4510):

  • Bind
  • Search
  • Add
  • Modify
  • Delete

It also supports a number of popular LDAP controls and extensions:

LDAP controls:

  • Authorisation identity bind control (RFC 3829).
  • Server-side sorting of search results (RFC 2891).
  • Simple paged results (RFC 2696).
  • Virtual-list-view search control (draft-ietf-ldapext-ldapv3-vlv-09)
  • Sub-tree delete (draft-armijo-ldap-treedelete-02).

Extended LDAP operations:

  • Password Modify (RFC 3062)
  • StartTLS (RFC 4511)
  • Who am I (RFC 4532)

Directory server compatibility

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

Popular proprietary directory servers:

Popular open source directory servers:

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 »
Directory write operations » Extended directory operations » Utility functions »
Directory schema information » SRP-6a authentication »
Web service information »

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 through a set of properties located in the /WEB-INF/json2ldap.properties file.

Access control » Web API settings »

Client access control: SSL / X.509 security, client IP whitelist, API keys.

Enable / disable Json2Ldap calls, exception reporting, HTTP response content type.

LDAP connections » Default LDAP server »

LDAP connection settings: directory server whitelists, security, auto-reconnect, time limits.

Specify a default LDAP directory server (single / replicated) for ldap.connect requests.

Custom trust / key store for TLS/SSL LDAP » SRP-6a authentication »

Custom trust and / or key store for TLS / SSL LDAP connections.

Optional settings for Secure Remote Password (SRP-6a) authentication.

Logging

Json2Ldap uses the popular Log4j framework. The following event types 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 by the /WEB-INF/log4j.properties file.

Example LDAP directory server

An example LDAP directory server is included in the Json2Ldap WAR to enable evaluation and testing of the service without an external directory. The example directory is enabled / disabled and configured through the /WEB-INF/exampleDirectory.properties file.

System requirements and dependencies

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

  • Java 7+

  • Java servlet API 2.5+

The web service requires about 100 megabytes of memory to boot, then about 1 kilobyte for each open LDAP connection.

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.
  • version 2.3 (2012-03-28)
    • Adds a “binaryAtributes” parameter to ldap.getEntry and ldap.search to specify explicit Base64-encoding of binary attribute values. All attributes specified by the “attributes” parameters are returned encoded as UTF-8 strings.
    • UTF-8 becomes the default and required character encoding for all JSON-RPC 2.0 responses. This is achieved by making “charset=utf-8” a mandatory part of the json2ldap.clients.responseContentType configuration property.
    • Updates NimbusDS Common JAR (formerly LDAP Util) to 1.4.
    • Updates JSON Smart JAR to 1.1.
    • Updates JSON-RPC 2.0 Base JAR to 1.25.
    • Updates JSON-RPC 2.0 Server JAR to 1.5.
  • version 2.3.1 (2012-04-03)
    • Updates JSON Smart JAR to 1.1.1.
    • Updates JSON-RPC 2.0 Base JAR to 1.25.1.
    • Updates JSON-RPC 2.0 Server JAR to 1.5.1.
  • version 2.3.2 (2012-06-19)
    • Fixes bug in json2ldap.clients.requireAuthentication checking.
    • Updates UnboundID SDK JAR to 2.3.1.
  • version 2.3.3 (2012-07-22)
    • Updates JSON-RPC 2.0 Base JAR to 1.27.
    • Updates JSON-RPC 2.0 Server JAR to 1.6.
    • Updates NimbusDS Common JAR to 1.8.
    • Updates Property Util JAR to 1.6.
    • Removes Apache Commons Lang JAR dependency.
  • version 3.0 (2013-01-07)
    • Adds optional “normalize” attribute names parameter to ldap.getEntry, ldap.search and ldap.getRootDSE requests.
    • Adds support for Virtual List View ldap.search control (draft-ietf-ldapext-ldapv3-vlv-09).
    • Renames enumerated ldap.search scope SUBORDINATE_SUBTREE parameter value to SUBORDINATES (LDAP URL compatible).
    • Adds support for a default LDAP server set to facilitate fail-over and round-robin ldap.connect operation.
    • Adds support for API keys (via new JSON-RPC 2.0 Access Filter dependency).
    • Refactors Json2Ldap configuration.
    • Implements json2ldap.api.exposeExceptions configuration parameter for JSON-RPC 2.0 “Internal error” responses.
    • Logs configuration parameters at startup.
    • Adds JSON-RPC 2.0 Access Filter JAR 1.3 dependency.
    • Upgrades NimbusDS Common JAR to 1.52.
    • Upgrades Nimbus SRP JAR to 1.4.
    • Upgrades JSON-RPC 2.0 Base JAR to 1.31.
    • Upgrades JSON-RPC 2.0 Server JAR to 1.8.
    • Upgrades Log4j JAR to 1.2.17.
    • Upgrades CORS Filter JAR to 1.5.
  • version 3.0.1 (2014-03-09)
    • Changes branding and licence texts to Connect2id.
    • Upgrades Common JAR to 1.76.1.
    • Adds Apache Commons Dependency JAR 1.9.
    • Upgrades CORS Filter JAR to 1.9.2.
    • Upgrades Property Utils JAR to 1.9.1.
    • Upgrades JSON-RPC 2.0 Base JAR to 1.35.
    • Upgrades JSON-RPC 2.0 Server JAR to 1.10.1.
    • Upgrades JSON-RPC 2.0 Access Filter JAR to 1.4.3.
    • Upgrades UnboundID LDAP SDK JAR to 2.3.5.
  • version 3.0.2 (2014-04-08)
    • Upgrades Common JAR to 1.76.1.
    • Upgrades UnboundID LDAP SDK JAR to 2.3.6.
  • version 3.0.3 (2014-06-07)
    • Prepends slash to configuration file locations in web.xml descriptor (required by JBoss EAP).