Category Archives: Java

JSON-RPC and cookies

JSON-RPC ShellToday’s releases of the JSON-RPC 2.0 Client (version 1.6) and JSON-RPC 2.0 Shell (version 1.10) include support for handling HTTP cookies, just like browsers do. These latest updates came about after a developer in Norway wrote that the JSON-RPC software was not working as expected against the web API of a particular service provider. A quick look at the API docs revealed that the service was pushing session tokens outside the regular JSON-RPC message flow, using HTTP cookies. The inclusion of cookie support took about a day to code and test out and is now publicly available.

I know, to purists using out-of-channel means to pass the session tokens of a JSON-RPC service is not a clean thing to do. I also value the simplicity of having all message data passed in-channel and our JSON-RPC based services – from Json2Ldap to JsonSSO use the regular JSON-RPC parameters and result fields to communicate session tokens. But at the same time, if you’re programming a servlet-based web service, using the built-in session mechanisms can be too convenient (and routinely done) to ignore.

There is another pitfall with passing cookies from a JSON-RPC service: if you want to allow cross-domain XHR access from browsers to your service, IE will certainly block any cookies for security reasons.

So my advice is to stay away from cookies in JSON-RPC, despite their relative convenience.

JSON-RPC for Android apps

JSON-RPC 2.0 Thanks to user feedback I recently discovered that the JSON-RPC 2.0 Base and related libraries and JSON-RPC shell are finding increasing use in Android applications, mostly to hook to remote JSON-RPC services.

While I’m not really into mobile gadgets and don’t own a smart phone, I do sense there is usefulness in mobile apps to people. I’m now considering a mobile version of the Json2Ldap demo. The upcoming Transaction Company software will also certainly a boast a few mobile apps, to allow users to check their balance and pay co-workers while on the go. Application Craft‘s offering may be just the right mean to do that, as it provides both a development and hosting environment in one.

CORS requests and cookies

CORS FilterToday I received a question regarding the Java CORS Filter and browser cookies:

Does your filter take care about the sessions? For each CORS request I get a different JSESSIONID.

My response was that in order for the Java web application or service to get at a cookie, both the CORS Filter in front of it as well as the requesting JavaScript must explicitly allow this form of credential:

First, the JavaScript initiating the XHR call must set its “withCredentials” flag to true. Otherwise the browser will not allow any cookies to be passed during the cross-domain call.

var xhr = new XMLHttpRequest();
var url = 'http://bar.other/resources/credentialed-content/';'GET', url, true);
xhr.withCredentials = true;
xhr.onreadystatechange = handler;

Second, the CORS Filter must also expressly state to the browser that cookies are permitted. This is advertised during the so called “pre-flight” request that the browser makes before an actual request that may involve credentials, such as cookies. The CORS Filter ships with a default configuration where credentials, such as cookies, are flagged as allowed when responding to preflight requests. To restrict this edit the cors.supportsCredentials configuration parameter.

The Java CORS filter itself doesn’t access the cookie headers in any way, nor does it interface to the JSESSIONID.

So, to sum up, both the calling script on the browser side as well as the CORS Filter on the server side must expressly have the credentials flag enabled for cookies to pass through.

There is a snag however and it has to do with Internet Explorer. Its XDomainRequest implementation of CORS doesn’t allow cookies to be passed at all, for security reasons says Microsoft. Which is probably a good thing. So if you wish to achieve wider browser support for your cross-domain application or service you will have to use an alternative mean to cookies for storing session IDs, such as passing the token as an URL parameter.

Easy LDAP user authentication over the web

NimbusDS AuthServiceAuthService is a simple web service software offered by Nimbus Directory Services. It can authenticate users against any LDAP directory using a web-friendly HTTP+JSON protocol.

Where to use?

AuthService can be used in any situation where you have to authenticate user credentials (login) over the web against an LDAP-compatible directory such as Microsoft Active Directory, Novell eDirectory or OpenLDAP.

  • You’re a SaaS provider and want to provide your corporate customers with a method for authenticating users against their internal directory.
  • Your company has applications in the cloud and wish them to use the corporate directory for user login.
  • You’re designing an Ajax app and want to authenticate users with a single JSON XHR. No redirection and page reloading, please!

How does it work?

AuthService is a nimble web service that sits in front of an LDAP directory and receives JSON-RPC request from web clients. It resolves the supplied usernames to valid directory entry entries (DNs) and translates between the binary LDAP protocol and HTTP/JSON.

AuthService authenticates users against an LDAP-compatible directory

The JSON request and response messages, what do they look like?

AuthService communicates with simple JSON messages. These follow the standard JSON-RPC 2.0 protocol.

Example user authentication request:

  "method"  : "user.auth",
  "params"  : { "username" : "",
                "password" : "s3cr3t" },
  "id"      : "0001",
  "jsonrpc" : "2.0" 

And here is an example response indicating the supplied username and password were correct:

  "result"  : true,
  "id"      : "0001",
  "jsonrpc" : "2.0"

The complete AuthService web API is documented online.

Can you retrieve a user’s details from the directory?

Yes! In addition to checking the user’s credentials you can also configure AuthService to return a selected set of user’s directory entry attributes on auth success. This is done via the authService.userAttributes configuration setting.

Here is a sample list of attributes that can typically be retrieved:

  • Given name, surname, full name.
  • Email address.
  • Office, home and mobile phone numbers.
  • Organisational details such as manager, department and authorisations / permissions.

Here is an example of such a JSON user auth response that returns selected user details:

{ "result"  : { "userID" : "alice",
                "name"   : "Alice Wonderland",
		"email"  : "",
		"phone"  : "+44 711 567 8910" }
  "id"      : "0001",
  "jsonrpc" : "2.0"

Which directory servers is AuthService compatible with?

AuthService works with any LDAP v3 compatible directory. This includes Microsoft Active Directory, Novell eDirectory, IBM’s and Oracle’s directory services, the open source OpenLDAP, OpenDJ and ApacheDS servers.

What about installation?

AuthService is delivered as a standard Java servlet application, packaged as a WAR file and ready for immediate installation into any Java web server, such as the popular free Apache Tomcat or Jetty servers. The WAR file weighs a nimble 2.5 megabytes.

How about security?

AuthService includes a number of configuration settings for managing and protecting access to the service.

  • Whitelist of allowed client IPs / hostnames that may access the service.
  • Whether secure HTTPS is mandatory.
  • Whether clients are required to authenticate with a valid X.509 certificate issued by a trusted certificate authority (CA).
  • Whether the subject of the presented X.509 client certificate must match an authorised distinct name (DN).

What about price and support?

AuthService licenses come at a super affordable price. For immediate purchase and download check out the NimbusDS online shop. Attractive discounts are available if you with to distribute the software as part of your own product or SaaS offerings, for 100, thousand or even more copies.

NimbusDS, which operates out of London, UK and Bulgaria, also offers excellent integration and consulting services, with emphasis on LDAP directory design, meeting organisational objectives, web and cloud directory applications.

The NimbusDS line gets a speed boost

The Nimbus Directory Services product lineThe complete Nimbus Directory Services product line received a speed boost in June. The latest versions of Json2Ldap, JsonSSO and AuthService now feature a greatly improved JSON parser which speeds up decoding of incoming requests by impressive 380 per cent!

Thanks to Uriel Chemouni from the JSON Smart project for his top work!

What is next on the immediate NimbusDS roadmap?

So, expect more good news as we are heading into the summer. Here in London we had quite a promising start, warm and sunny!

JSON-RPC 2.0 Base flies with the new JSON library

JSON-RPC 2.0Two years after its initial release the JSON-RPC 2.0 Base library switches to a new package for representing and parsing JSON messages. The result is 2x to 4x times faster performance in JSON-RPC message parsing!

Back in 2009 I chose JSON Simple for its simple and relatively non-invasive model for representing and mapping JSON entities to Java primitives and objects. Performance was also relatively good against the alternatives, so JSON Simple became the natural choice for the JSON-RPC 2.0 Base classes. JSON Simple development became stale with time however, and more than 2 years passed without any new releases or fixes to reported bugs. This, I suspect, must have led to the user community becoming somewhat frustrated and a fork imminent.

A fork of JSON Simple did indeed arrive, in May this year, initiated by Uriel Chemouni and named JSON Smart. Initial tests showed considerable performance gains and after some email exchange with Uriel which resulted in the addition of strict JSON parsing, JSON Smart became the new library for JSON-RPC 2.0 Base.

So what do you gain with the new release?

JSON-RPC message parsing is sped up 2.4 times for the reusable JSONRPC2Parser and 3.8 times for the static parse methods.

Parse performance for JSON-RPC 2.0 messages

Moreover, the difference in terms of performance between the static parser and the instance parser is almost negligible, which means that for apps like servlets there is no need to pool parsers in order to speed up request processing.

Thanks for Uriel for making this great piece of software!

In the next few days Json2Ldap and the other products in the NimbusDS line will receive the new library, so expect more good news!

LDAP directory in the cloud

Json2Ldap iconJson2Ldap hit the cloud this month.

I’ve always wanted to put up an online demo for the JSON web service for LDAP directory access and this is reality now. If you visit the NimbusDS website you’ll see a new Json2Ldap demo page where you can play with three Ajax directory applications:

  • Online employee directory: Presents a list of company employees where by clicking on a person’s name additional details are displayed.
  • Resolving group membership: An important organisational feature of directories is the ability to specify groups for things like departments, permissions and mailing lists. This app lists the available groups and resolves the associated members.
  • User authentication: Ajax form to authenticate a user’s UID and password against their LDAP directory account.

The Ajax apps were written in JavaScript and use a relatively small subset of Json2Ldap’s web API, namely the JSON requests ldap.connect,, ldap.getEntry, ldap.simpleBind and ldap.close.

Ajax employee directory

As for the directory web service, I set up a Json2Ldap instance at CloudBees, together with an embedded in-memory LDAP directory that represents a typical corporate DIT consisting of a user base and several groups. You can view a screenshot of the directory tree to get an idea of its user and group structure. In a deployed state Json2Ldap with the in-memory directory take up 40 MB of memory which fit nicely into the free PaaS plan of CloudBees (256 MB).

The directory behind Json2Ldap can of course be any other LDAP v3 compatible server, such as Microsoft Active Directory, Novell eDirectory, OpenLDAP, OpenDJ, etc. So there’s complete flexibility here, also in terms of schema, as Json2Ldap is schema-agnostic.

How about Ajax responsiveness?

Measurements with the JSON-RPC Shell show that JSON calls to the Json2Ldap service at CloudBees are typically completed in about 150 ms. I don’t have a basis for comparison with other cloud vendors here, but I suppose responsiveness impacted by the relative datacentre location (e.g. EU vs USA) and the efficiency of the PaaS abstraction layers of CloudBees. Their PaaS is actually running on top of Amazon’s cloud infrastructure, so there may be quite many layers involved. When I compare the response time to a Json2Ldap service on the local intranet, the JSON calls here take about 15 ms to complete, which is an order of magnitude quicker. For the actual demo apps the 150 ms response time however is okay and doesn’t affect responsiveness in a noticeable way. You can of course try it out for yourself.

The next planned cloud demos will cover the other NimbusDS software products – JsonSSO and AuthService.

Json2Ldap offers new LDAP utility functions

Json2Ldap iconJson2Ldap, the LDAP gateway for accessing directory servers from web devices and browser applications, now offers a new set of utility functions. These are related to distinct name (DN) processing and search filters. This new functionality is available in the latest Json2Ldap 1.8, which was released on 17 March.

Here I’ll give you a brief overview of what these functions do and how you may use them. Note that these are quite simple JSON-RPC requests that don’t require a connection to the back-end directory. They are “static” and you can use them without any prior LDAP connection set up.

DN functions

A set of functions related to distinct name (DN) processing.

  • ldap.util.isValidDN Allows checking of DN validity. Use to validate DNs input by users or read from configuration files.
  • ldap.util.normalizeDN Quick function for normalising a DN string. It removes all redundant whitespace and converts all characters to lower case (assuming the RDN component values are case-insensitive). Use if you intend to use the DN as a key in a hash map or if you want to store it in a normalised form.
  • ldap.util.compareDNs Compares two DNs for equality, taking account of multi-valued RDNs if any.  Use it to make sure two DNs are equal.

Here is an example JSON-RPC 2.0 request to validate a DN string:

{ "method"  : "ldap.util.isValidDN",
  "params"  : { "DN" : "cn=Alice Wonderland,ou=people,dc=example,dc=com" },
  "id"      : 1,
  "jsonrpc" : "2.0" }

And the corresponding JSON-RPC 2.0 response:

{ "result"  : true,
  "id"      : 1,
  "jsonrpc" : "2.0" }

Search filters

At present there is only one utility function related to search filter. I plan to add another one in the next Json2Ldap version, to validate search filters.

  • ldap.util.encodeFilterValue Encodes a search filter assertion value. Use it to escape special characters when you process user input into search templates like (!(uid=%u)(mail=%u)).

Example JSON-RPC 2.0 request:

{ "method"  : "ldap.util.encodeFilterValue",
  "params"  : { "value" : "a*b*c" },
  "id"      : 1,
  "jsonrpc" : "2.0" }

The corresponding JSON-RPC 2.0 response. Note how the asterisk chars (which normally constitute a wild-card) were escaped.

{ "result"  : "a\2ab\2ac",
  "id"      : 1,
  "jsonrpc" : "2.0" }

The complete web API documentation of Json2Ldap is available here.

JSON-RPC 2.0 Shell, version 1.6

Today I sent an email to my growing JSON-RPC 2.0 Shell fan base that a new release has come out.

So, what is new in the latest 1.6 version?

  • Pretty JSON formatting now has extra options. With the -p, –pretty (compact|regular|off) command line option you can now select between two formatting styles or turn pretty styling entirely off.
  • Per suggestion of Sven Schwarz, the -n, –no-strict option turns checking of the “jsonrpc” field off, thus enabling (limited) compatibility with the original (1.0) JSON-RPC protocol.
  • Also, to ease testing over HTTPS connection, there is now a -t, –trust-all command line option to accept self-signed certificates or certificates signed by a CA that is not in the default Java trust store.

The updated JSON-RPC 2.0 Shell manual is at