Json2Ldap datasheet

JSON-RPC web service for LDAP directory access

The Json2Ldap is a JSON-RPC 2.0 web gateway for LDAP directory access.

Supported LDAP operations and controls

Json2Ldap supports all core LDAP operations (RFC 4510):

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

LDAP controls:

Extended LDAP operations:

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 deployment in a Java servlet container, such as the popular open source Apache Tomcat server.

Configuration

Json2Ldap can be configured by 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.

Sample LDAP directory server

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

System requirements and dependencies

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

  • Java 8+

  • 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 distributed Json2Ldap WAR file.

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).
  • version 3.0.4 (2014-11-19)
    • Extends LDAP filter error message to include debugging information.
  • version 3.0.5 (2014-11-19)
    • Provides additional error message information on an LDAP error if available.
  • version 3.0.6 (2015-05-28)
    • Reimplements json2ldap.ldap.requireSecureAccess configuration setting. version 3.1 (2017-07-20)
    • Switches to Log4j 2 logging, which is now configured by /WEB-INF/log4j.xml.
    • Refactoring and clean up of source code.
    • Upgrades Apache Commons Codec to 1.10.
    • Upgrades NimbusDS Common to 1.108.1.
    • Upgrades CORS Filter to 2.5.
    • Upgrades Property Utils to 1.10.
    • Upgrades JSON Smart to 1.3.1.
    • Upgrades JSON-RPC 2.0 Base to 1.38.
    • Upgrades JSON-RPC 2.0 Server to 1.11.
    • Upgrades JSON-RPC 2.0 Access Filter to 1.5.1.
    • Upgrades Nimbus SRP 6a to 2.0.2.
    • Upgrades UnboundID LDAP SDK to 3.2.1.
    • Upgrades Log4j to 2.8.2. version 3.1.1 (2017-08-25)
    • Fixes example directory server file locations to ensure proper loading under all OS. version 3.2 (2017-08-25)
    • Upgrades to Java 8.
    • Upgrades UnboundID LDAP SDK to 4.0.0.
    • Upgrades NimbusDS Common to 2.6.
    • Renames /WEB-INF/exampleDirectory to /WEB-INF/sampleDirectory
    • Renames sample directory properties to sampleDirectory.*