Products » Json2Ldap »

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 any directory supporting the current version 3 of the Lightweight Directory Access Protocol (LDAP).

Popular 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 is configured by properties located in the /WEB-INF/json2ldap.properties file. Every file-based configuration property can be overridden by a Java system property.

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 4.0.1+

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.*
  • version 3.3 (2020-02-24)
    • Enables Json2Ldap to be configured with Java system properties, overriding settings in the "json2ldap.properties" file.
    • Updates /WEB-INF/log4j.xml to support console logging. To log to the console (stdout) set the "log4j.loggers.root.appender" Java system property to "console". To set the logging level set the "log4j.loggers.root.level" Java system property to the desired level, e.g. to "debug", ""info", "warn", or "error". The default level is "info".
    • Updates UnboundID LDAP SDK to 4.0.14.
    • Updates NimbusDS Common to 2.37.
    • Updates Property Utils to 1.14.
    • Updates CORS Filter to 2.9.
    • Updates Log4j to 2.13.0.
  • version 3.3.1 (2020-03-07)
    • Upgrades JSON-RPC 2.0 Access Filter to 1.6 to enable Java system properties override for json2ldap.access.*.
    • Updates UnboundID LDAP SDK to 5.0.0.
  • version 3.4 (2020-10-22)
    • Adds alternative ldap.delete call where the entry to delete is specified by a named parameter "LDIF" containing a LDIF string of change type DELETE.
    • Updates UnboundID LDAP SDK to 5.1.1.
  • version 3.4.1 (2020-10-22)
    • Fixes software version in web.xml display-name.
  • version 3.4.2 (2021-12-10)
    • Updates JSON Smart to 1.3.3.
    • Updates Log4j to 2.15.0.
  • version 3.4.3 (2021-12-16)
    • Updates Log4j to 2.16.0.
    • Updates UnboundID LDAP SDK to 6.0.3.
    • Updates JSON Smart to 2.4.7.
    • Updates JSON-RPC 2.0 Access Base to 2.0.
    • Updates JSON-RPC 2.0 Access Server to 1.11.1.
    • Updates JSON-RPC 2.0 Access Filter to 1.7.
    • Updates Property Utils to 1.14.
    • Updates CORS Filter to 2.10.
  • version 3.4.4 (2021-12-22)
    • Reverts UnboundID LDAP SDK to 5.1.4.
    • Updates Log4j to 2.17.0.
    • Updates JSON-RPC 2.0 Access Filter to 1.7.1.
  • version 3.4.5 (2022-01-11)
    • Updates Log4j to 2.17.1.
  • version 3.4.6 (2022-01-12)
    • Fixes the compilation target for Java 8.
  • version 3.4.7 (2022-01-13)
    • Fixes dependency packaging for JSON Smart 2.4.7.
  • version 3.4.8 (2022-01-13)
    • Web.xml version fix.
  • version 3.5 (2023-03-10)
    • Adds JSON-RPC 2.0 error to HTTP status code mapping. LDAP errors receive the HTTP status code 460, Json2Ldap API specific errors 461, access denied class of errors codes 401 and 403, JSON-RPC 2.0 core errors 400 (with -32603 Internal error receiving 500).
    • New optional json2ldap.api.disableErrorCodeMapping configuration property to disable the introduced JSON-RPC 2.0 error to HTTP status code mapping with a default value of false. When disabled the Json2Ldap API will revert to previous behaviour where all JSON-RPC 2.0 errors are encapsulated in HTTP 200 Success responses.
    • Upgrades to NimbusDS Common to 2.51.
    • Updates JSON Smart to 2.4.8.
    • Updates Log4j to 2.20.0 (web to 2.19.0).
    • Adds Nimbus JOSE+JWT 9.31.
  • version 3.5.1 (2023-06-12)
    • Updates UnboundID LDAP SDK to 6.0.8.
    • Updates JSON Smart to 2.4.10.
  • version 3.6 (2023-07-03)
    • Updates the minimum required Java Servlet API to 4.0.1 to enable installation of Json2Ldap add-ons with Servlet annotations.