Json2Ldap :: Quick Start

Download and unzip

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

Deploy

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

json2ldap.war

You need to deploy this WAR package into 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're using Apache Tomcat, simply copy the WAR file to the webapps/ directory of your Tomcat installation and restart the server. The server will then automatically extract the content of the WAR package into a directory called webapps/json2ldap/ and start the Json2Ldap service.

Other web servers may have a different WAR deployment procedure, through a web UI or from the command line. This should generally be a simple and quick thing to do.

Configure (optional)

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

The Json2Ldap configuration is stored as a set of parameters in the standard web app descriptor file

WEB-INF/web.xml

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

Verify

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

http://localhost:8080/json2ldap/

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

If the Json2Ldap service is up and running you should see the following text message in your browser:

Use HTTP POST to submit your JSON-RPC 2.0 request

Web service: Json2Ldap, version 2.2 (2011-12-27)
Vendor: Nimbus Directory Services, http://nimbusds.com

This message basically says that the service expects JSON-RPC 2.0 requests received via HTTP POST.

Usage

The JSON remote procedure calls (RPC) served by Json2Ldap are described in the web API reference.

You can make use of about 20 JSON calls which provide you with all standard LDAP directory operations as well as a number of useful extensions. These can be scripted from web browsers using XHR or through popular JavaScript libraries such as jQuery. Of course, Json2Ldap is not just for browser JavaScript apps, you can use it from just about any programming language and environment.

To get an initial taste of Json2Ldap and its JSON-RPC 2.0 interface you can make a few directory requests using the JSON-RPC 2.0 Shell (included in the download package). It behaves pretty much like a regular Windows or Unix CLI, but instead for issuing OS commands it allows for interaction 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 session, where we enter a few requests to connect to an LDAP server, authenticate and obtain a directory record's attributes (the input commands are in bold). The 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

Check the file JSON-RPC shell manual if you need help with its command line arguments and usage.