Json2Ldap quick start

Download and unzip

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

Deploy

The Json2Ldap web service classes, required libraries and configuration files are packaged in a standard WAR file called

json2ldap.war

You need to deploy this WAR file on your Java web server. If you don’t have one you can grab a free copy of the popular open-source Apache Tomcat or Jetty servers.

If you have Apache Tomcat, simply copy the WAR file to the webapps/ directory of your Tomcat installation. Tomcat will then automatically extract the content of the WAR into a directory called webapps/json2ldap/ and start the Json2Ldap service.

Other web servers may have a different WAR deployment procedure, involving a web UI or the command line.

Configure (optional)

Json2Ldap can be run straight out of the box, without any additional configuration. However, do look at its various configuration parameters, particularly if you intend to put the software to serious use.

Json2Ldap is configured by a set of parameters in a Java properties file. On Apache Tomcat this would be

webapps/json2ldap/WEB-INF/json2ldap.properties

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.0 (2013-01-04)
Vendor: Connect2id Ltd., http://connect2id.com

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

It basically says that Json2Ldap expects JSON-RPC 2.0 requests received by HTTP POST.

Play

The web API reference provides a detailed description of the JSON Remote-Procedure Calls (JSON-RPC 2.0) served by Json2Ldap. The 20 or so JSON calls cover all standard LDAP directory operations and a number of useful extensions. They can be scripted from web browsers using direct XHR or from any other application or platform with access to the web.

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 pretty much 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/

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 record.

The target LDAP server is the 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=wondlerland,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.