Skip to content
Connect2id

Quick Start

Download and unzip

Extract the downloaded Json2Ldap ZIP package into a folder on your computer.

Deploy

The Json2Ldap bytecode, dependencies and configuration files are packaged in a standard Java WAR file called

json2ldap.war

Java 8+ and a standard Servlet 4.0.1+ compatible container (web server) are needed to deploy the Json2Ldap service. Apache Tomcat and Jetty are popular open source web servers which run servlet-based applications.

If you have Apache Tomcat, simply copy the json2ldap.war file to Tomcat’s webapps/ directory. Tomcat will then automatically extract the archive into a directory webapps/json2ldap/ and start the Json2Ldap service.

Other web servers may have a different method for deploying WAR files, via a web UI or the command line.

Configure (optional)

Json2Ldap can be run straight out of the box, with no additional configuration. But do look at its various configuration options before putting it into production.

Json2Ldap is configured by a Java properties file. In a Apache Tomcat deployment the file location is:

webapps/json2ldap/WEB-INF/json2ldap.properties

Every file-based configuration property can be overridden by a Java system property. A system property can be set with the -D Java command line argument like this:

-Djson2ldap.access.https.require=true

Remember to restart your Json2Ldap web service after updating the configuration!

Verify

Point your web browser to the URL where the Json2Ldap service was installed, e.g. to

http://localhost:8080/json2ldap/

assuming the web server is on localhost and it is listening on port 8080.

If the Json2Ldap service is up and running the following banner message will appear in your browser:

Use HTTP POST to submit your JSON-RPC 2.0 request

Web service: Json2Ldap, version 3.4.4 (2021-12-22)
Vendor: Connect2id Ltd., http://connect2id.com

Supported JSON-RPC 2.0 requests:
	* ldap.add
	* ldap.anonymousBind
	* ldap.close
	* ldap.compare
	* ldap.connect
	* ... more request names follow ...

Play

The web API reference provides a detailed description of the JSON Remote-Procedure Calls (JSON-RPC 2.0) served by Json2Ldap. The 39 JSON calls cover all standard LDAP directory operations and many useful extensions. They can be scripted from web browsers using XHR or from any other client application which can make HTTP requests.

For a quick test of the Json2Ldap web API you can make a few directory requests using the JSON-RPC 2.0 Shell (included in the downloaded package). It behaves like a regular Windows or Unix CLI, but instead for issuing OS commands it interacts with a remote JSON-RPC server.

Start the JSON-RPC 2.0 Shell like this, specifying the Json2ldap URL:

java -jar jsonrpc2-shell.jar --auto-id 0 http://localhost:8080/json2ldap/

Caveat: The trailing slash / in the URL is important!

This will open a shell session to the specified HTTP URL where Json2Ldap is accepting JSON-RPC 2.0 requests. The --auto-id 0 option turns on automatic appending of request IDs to outgoing JSON-RPC requests.

JSON-RPC 2.0 Shell, version 1.12 (r)

Hints:
        1. Example request with positional parameters and an ID of zero:
                JSON-RPC 2.0 > addNumbers [10,20] 0
        2. Example request with named parameters and an ID of one:
                JSON-RPC 2.0 > divideNumbers {"dividend":27,"divisor":3} 1
        3. Example notification with no parameters:
                JSON-RPC 2.0 > notifyIdleState
        4. To avoid typing request IDs repeatedly invoke the shell with
           the -a/--auto-id option and specify a default ID value
        5. Press [Ctrl] + [C] to exit
JSON-RPC 2.0 >

Here is an example request session, where we connect to an LDAP server, authenticate as alice, then retrieve selected attributes from her directory entry.

The target LDAP server is an example directory included with the Json2Ldap WAR which listens on port 10389.

The individual JSON requests are explained in detail in the Json2Ldap API reference.

JSON-RPC 2.0 > ldap.connect { "host" : "localhost", "port" : 10389 }
{"CID":"45d0677d-a336-463b-ad99-c82137d03a00"}


JSON-RPC 2.0 > ldap.simpleBind { "CID" : "45d0677d-a336-463b-ad99-c82137d03a00",
                                 "DN" : "uid=alice,ou=people,dc=wonderland,dc=net",
                                 "password" : "secret" }
{ }


JSON-RPC 2.0 > ldap.getEntry { "CID" : "45d0677d-a336-463b-ad99-c82137d03a00",
                               "DN" : "uid=alice,ou=people,dc=wondlerland,dc=net",
                               "attributes" : "cn mail telephoneNumber"}
{ "DN"              : "uid=alice,ou=people,dc=wondlerland,dc=net",
  "cn"              : [ "Alice Adams" ],
  "mail"            : [ "alice@wonderland.net" ],
  "telephoneNumber" : [ "+1 010 154 3228" ] }


JSON-RPC 2.0 > ldap.close { "CID" : "45d0677d-a336-463b-ad99-c82137d03a00" }
null

The JSON-RPC shell manual provides further information about its command line arguments and use.

Get in touch with our support should you need help with the Json2Ldap web API and its integration into your web application.