FAQ

1. What security features does Json2Ldap offer?

Json2Ldap is not just about giving developers a nice JSON web API
for dealing with LDAP directories. It also provides a number of security
features, such as:

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:

5. How to deal with international characters?

UTF-8 is the default character set for JSON
messages and for LDAP strings. Therefore
Json2Ldap will always return UTF-8 encoded content.

To avoid gibberish in your request parameters when dealing with non-ASCII
strings, which may occur in DNs, search filters and attribute values, set your
HTTP request content type header accordingly and make sure your strings are
output in UTF-8 too:

Content-Type: application/json; charset=utf8

If you don’t do that you may get unexpected results, such as search filters not
matching or attributes with garbled values.

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

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

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.

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

9. 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:

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.

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

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

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

13. 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 :)

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