FAQ

1. What security features does Json2Ldap offer?

Json2Ldap is not just about providing a JSON web API to LDAP directories. It also offers comprehensive security to protect identities and data, and to to minimise exposure to denial-of-service:

  • LDAP server whitelists.

  • Connection quotas per client IP and authenticated user (bind DN).

  • Use of secure connection identifiers (CID).

  • Clients may be required to authenticate with LDAP “bind” at connection time.

  • Allowing the hostname/IP address of the back-end LDAP server to remain hidden from web clients.

  • TLS/SSL may be required for web client access to Json2Ldap, or for connections to the backend LDAP directory.

  • Directory access may be limited to read-only or authenticate-only.

2. How do I set a user password in Microsoft Active Directory?

In Active Directory (AD) the password attribute is called unicodePwd. The password value is expected to be provided in the following format: surrounded by quotes and encoded as a UTF-16 (little-endian) string. For example:

"secret"

Failing to meet the unicodePwd encoding criteria will result in the following LDAP error:

Server is unwilling to perform (53)

MS AD also requires an SSL/TLS LDAP connection for all password modify requests. A plain (unsecured) connection will not work.

JSON mandates a UTF-8 encoding and so does Json2Ldap by extension. To work around this and feed a UTF-16 string to MS AD we suggest use of the optional binary parameter of ldap.add / ldap.modify:

The steps:

  1. Produce the UTF-16 password string as expected by AD. Don’t forget the double quotes!

  2. Encode it into a BASE64 string.

  3. Set the optional binary parameter true.

3. How do I set the user password in other directories?

The preferred method for setting user passwords in other LDAP servers is the password modify extended operation. It is supported by the following LDAP servers:

  • OpenLDAP
  • OpenDJ
  • 389 Directory Server

The above list is not exhaustive.

4. cURL

You can use the popular cURL command line utility to send requests to Json2Ldap.

Example ldap.connect request with cURL:

curl -H 'application/json' --data-binary '{"method":"ldap.connect","id":1,"jsonrpc":"2.0"}'

The -H parameter sets the Content-Type HTTP request header.

The --data-binary parameter sets the HTTP POST body (with the the JSON-RPC 2.0 request).

5. Why do I get an LDAP error 11 (Admin Limit Exceeded) when making searches?

This error is raised when the so-called “look through” limit is exceeded. If you’re using OpenDS set the ds-cfg-lookthrough-limit configuration parameter to a value that is greater than the total number of entries in your directory.

6. Setting up client X.509 certificate authentication

On the client side:

If you’re using a Java client library to connect to Json2Ldap, such as the open source JSON-RPC 2.0 Client, you need to specify the key store where the client’s public certificate and its private key are stored.

This can be done by setting the following system properties, either with the -D switch to the java command, or with System.setProperty from within your client code:

javax.net.ssl.keyStoreType=jks
javax.net.ssl.keyStore=path/to/keystore.jks
javax.net.ssl.keyStorePassword=secret

You can find more information in the following Stack Overflow post.

On the server side:

The client certificate must also be imported into a Java trust store which is made available to the web server (e.g. Tomcat) where Json2Ldap is installed.

This can be done by setting the following system properties to the web server:

javax.net.ssl.trustStoreType=jks
javax.net.ssl.trustStore = path/to/truststore.jks
javax.net.ssl.trustStorePassword=secret

More on the difference between key and trust stores.

Looking for a key store GUI?

The excellent Key Store Explorer can save you the hassle of dealing with the keytool command line utility directly, for all common tasks such as viewing a keystore’s content or importing / exporting keys and certificates.

7. Why JSON-RPC 2.0?

JSON-RPC provided a clean path to keep the spirit of the original LDAP protocol. Moreover, its RPC messages can flow nicely through web sockets (on our road map).

Version 2.0 of JSON-RPC was chosen over 1.0 because it enables named parameters, improving API clarity and allowing us to add new request parameters in future without breaking backward compatibility. JSON-RPC 2.0 also has better error reporting.

8. Why not a RESTful web API?

REST was given serious consideration. In the end JSON-RPC was deemed more appropriate for Json2Ldap for two reasons:

  1. The objective of Json2Ldap was to mimic the nature of the original LDAP protocol as closely as possible, while using JSON to encode the messages.

  2. Utility functions such as ldap.util.isValidDN and ldap.util.normalizeDN do not fit well in the concept of REST.

9. How about DSML?

DSML is, well, what the acronym implies - it’s dismal :-) The first version of this protocol was devised in 1999, but it didn’t really pick up, and even the subsequent revision in 2001 wasn’t particularly successful.

Using JSON to talk to directory servers over the web has significant advantages: In terms of format, JSON encoded messages are terse and easily consumed by JavaScript programs on the browser side. In terms of API, Json2Ldap keeps a close mapping to the LDAP protocol, so programmers who have previously worked with directories would feel immediately at home.

10. How does the Json2Ldap API compare to SCIM?

SCIM is a recent effort to provide RESTful access to identity data. Json2Ldap on the other hand offers a general purpose web API for working with any LDAP or virtual directory, and is not tied to a particular schema.

11. Cloud directory with Json2Ldap?

Json2Ldap can be fitted to any LDAP directory hosted in the cloud and web-enable it so that cloud-based or on-premise apps can conveniently work with identity data stored in it.

12. Why was the ldap.presetBind request removed from Json2Ldap in version 1.3?

The ldap.presetBind command was removed for the sake of simplicity. We realised that explaining the various security and configuration implications of this request was rather complicated, so we scrapped it from the Json2Ldap web API. Life should now be simpler for you and us too :)

13. How did Json2Ldap come about?

Json2Ldap was born as a by-product of a large software project in 2009. Its job was to present user identity data as a JSON web resource that is simple to integrate and manage, as part of a complex rich internet application (RIA).

Over the following years Json2Ldap quickly matured and is now serving a wide range of applications that benefit from web-friendly access to LDAP directory data - from Ajax apps to back-end software for provisioning and synchronising users onto cloud apps / SaaS.