LDAP articles

Json2Ldap 3.0.6

Posted on 2015-05-28

There is a new maintenance release of the Json2Ldap web API service for LDAP directory access.

Bug fixes:

  • Fixes the json2ldap.ldap.requireSecureAccess configuration setting to correctly identify and block non-TLS/SSL LDAP connection if the setting is enabled (iss #14, reported 2015-05-28).

The 3.0.6 maintenance release is available for download now.

Should you have any questions about the new release, don’t hesitate to contact our support.

Today we also updated the FAQ section with instructions how to set up a X.509 client certificate to provide an additional layer of authentication to clients and apps that access the Json2Ldap web API.

New monitoring and metrics for LDAP authentication

Posted on 2015-03-12

Keeping a close eye on performance and suspicious behaviour is indispensable when operating a critical enterprise service such as Single Sign-On (SSO) and Identity Provisioning (IdP).

The latest 3.2 release of the LdapAuth microservice adds a couple of JSON calls for DevOps to monitor LDAP authentication and the underlying infrastructure.

  • Usage monitoring — Get comprehensive statistics about successful and failed (due to bad credentials) authentication requests. Also, metrics on the requests that failed to an internal error, e.g. the LDAP backend directory being unavailable. Enables DevOps engineers to measure service level and to spot potential attacks, such as attempts to brute force passwords.

  • LDAP connection pool monitoring — Get detailed statistics about the pool of LDAP connections to the backend directory. Enables DevOps engineers to adjust the connection pool parameters for best performance.

Example usage stats:

{ "successfulAuthRequests" : { "m15_rate"  : 9.772683175949774E-7,
                               "m5_rate"   : 2.2680419495899147E-12,
                               "m1_rate"   : 2.4311455595109375E-48,
                               "count"     : 1,
                               "mean_rate" : 0.0000756265600749685,
                               "units"     : "events\/second" },
  "badAuthRequests"        : { "m15_rate"  : 0.0,
                               "m5_rate"   : 0.0,
                               "m1_rate"   : 0.0,
                               "count"     : 0,
                               "mean_rate" : 0.0,
                               "units"     : "events\/second" },
  "serverErrors"           : { "m15_rate"  : 0.0,
                               "m5_rate"   : 0.0,
                               "m1_rate"   : 0.0,
                               "count"     : 0,
                               "mean_rate" : 0.0,
                               "units"     : "events\/second" } }

LdapAuth is a micro-service for authenticating and provisioning users from an LDAP / Active Directory. Lightweight and flexible, it integrates nicely into web / mobile / cloud apps, or with with our Connect2id server for OpenID Connect Single Sign-On (SSO) and Identity Provisioning (IdP).

To get the latest version go to our downloads section.

Questions? Get in touch with Connect2id support.

Json2Ldap adds directory server fail-over and load-balancing

Posted on 2013-01-24

The new year began with the third major release of Json2Ldap, the cool JSON web API for accessing directory servers such as MS Active Directory, OpenLDAP and OpenDJ.

This post is a summary of what’s in the new 3.0 version.

Directory server fail-over and load-balancing

Resilience and scalability is a common requirement in enterprise and SaaS applications. You can now configure Json2Ldap to fail-over between two or more directory servers, or alternatively, to perform round-robin directory server selection.

Fail-over is a common strategy to provide backup in case your primary LDAP server fails. To handle such situations you can specify a secondary, tertiary, and so on servers for Json2Ldap to connect to if the primary becomes unavailable.

To configure fail-over:

json2ldap.defaultLDAPServer.selectionAlgorithm = FAILOVER
json2ldap.defaultLDAPServer.url = ldap:// ldap://
json2ldap.defaultLDAPServer.connectTimeout = 500

The above configuration will set a secondary LDAP server on IP Json2Ldap will direct new ldap.connect requests to it if it’s not able to connect to the primary server within 500 milliseconds.

Round-robin is the alternative server selection method. It provides for load-balancing between multiple servers and is also a form of fail-over in case one or more of the servers in the set become unavailable.

To configure round-robin selection with two servers, using again a connect time-out of 500ms:

json2ldap.defaultLDAPServer.selectionAlgorithm = ROUND-ROBIN
json2ldap.defaultLDAPServer.url = ldap:// ldap://
json2ldap.defaultLDAPServer.connectTimeout = 500

Configuration of fail-over and round-robin is explained in detail in the Json2Ldap docs.

Support for Virtual-List-View searches

The Virtual-List-View (VLV) control (draft-ietf-ldapext-ldapv3-vlv-09) allows web clients to retrieve an arbitrary subset of an LDAP search result. You can think of it as a sophisticated makeover of the Simple Paged Results (RFC 2696) control. The VLV control allows you to specify an offset into the result set and a number of entries to get before and after the offset position. This can for instance be of great help in devising efficient browsing web UIs when the result sets are expected to be huge.

To apply VLV to an ldap.search request add a parameter like this:

"vlv" : { "offset":50, "after":24 }

This will ask to return 25 entries at offset fifty. Note that the VLV control also requires the presence of a sort control in order to determine the entry order, e.g.:

"sort" : { "key":"givenName" }

I have put together a list of the directory servers that support Virtual-List-View. A brief look at the list will show you that it’s widely supported. You may however have to create specific indexes in your directory to enable it. Check you server documentation for that.

Use of the VLV control in Json2Ldap is detailed in the ldap.search API docs.

Normalising attribute names

The attribute names that Json2Ldap returns with ldap.getEntry, ldap.search and ldap.getRootDSE appear as defined in the directory schema. However, if you don’t have prior knowledge of their letter-case retrieving them from the result JSON object can be a bit of a problem.

var givenName = result["givenName"];

The solution to this has been to normalise all names, e.g. converting them to lower-case, before processing the result.

Json2Ldap 3.0 added a new optional normalize parameter to solve this problem. With it all attribute names in the result will be normalised, or converted to lower-case. So you don’t have to worry about the extra conversion. It will be done for you, quite efficiently, inside Json2Ldap.

Retrieving subordinate subtree entries

The ldap.search SUBORDINATE_SUBTREE scope parameter has been renamed to SUBORDINATES. This is the only breaking change in the Json2Ldap web API and was done to make the parameter compatible with the LDAP URL schema.

API keys

You can now also specify API keys to ensure only selected web clients can access the web API of Json2Ldap. These are passed as an optional apiKey parameter to each web call. You can define API keys for global access as well as keys that are only for certain API calls. Check out the API key configuration to find out more.

The classic X.509 client certificate access controls are still supported.

Simplified configuration files

Json2Ldap 3.0 moved the configuration parameters from the web.xml file to a set of simpler text properties files that continue to follow the established semantics. Many of the configuration properties were also given better and more intuitive names. As a result the whole task of configuring Json2Ldap should have become easier and less error-prone (by switching from XML to simple key / value properties). Adding a web UI configuration editor is on the roadmap for 2013 / 2014.

Ready to try out Json2Ldap 3.0?

You can get a copy of Json2Ldap 3.0 for evaluation from the product downloads section. Existing subscribers should have already been notified and received their download links for the full version.

[You’re welcome to get in touch with us if you have questions about the new version or feedback to share.

The full 3.0 change log is on the Json2Ldap datasheet.

LDAP user authentication explained

Posted on 2012-10-01

LDAP user authentication is the process of validating a username and password combination against a directory server such MS Active Directory, OpenLDAP or OpenDJ. LDAP directories are standard technology for centralised storage of user, group and permission information and serving that to applications in the enterprise.

Authenticating users against an LDAP directory is a two-step process. This article explains the mechanics of it and then how to configure it in LdapAuth.

Step 1 – Resolving the username to a directory entry attribute

User entries in a directory are identified by distinguished names (DNs) which resemble a path-like structure starting at the directory root:


In order to authenticate a user against an LDAP directory you need to obtain their DN as well as their password.

When you have a login form in your application, people typically enter a simple identifier such as their username or email address. You don’t expect them to memorise the DN of their directory entry. That would be impractical.

To solve this issue a DN resolution procedure is used. It takes the user’s name or email, then runs a search against the name or email attributes of all user entries to find the matching entry DN. Directories employ highly efficient indexing and caching, so these searches are typically very fast.

The directory attributes to search for are defined in the searchFilter configuration parameter. The default LdapAuth configuration searches the UID and email attributes. The %u placeholder is substituted with the user identifier entered in the login form:

ldapAuth.dnResolution.searchFilter = (|(uid=%u)(mail=%u))

If you want to search for UID only the search filter would look like this:

ldapAuth.dnResolution.searchFilter = (uid=%u)

If you want to search for UID, email and employee number, extend the filter to

ldapAuth.dnResolution.searchFilter = (|(uid=%u)(mail=%u)(employeeNumber=%u))

Two important things to observe when configuring DN resolution and creating new user entries in the directory:

  • The attributes – username, email, etc – with which users login must be unique. If two entries are found to have the same identifying attribute, e.g. email, authentication will be promptly denied.

  • Make sure every user who is expected to login has a defined attribute for the identifying attribute. For example, if users are going to login with their email address, make sure all accounts have a defined email attribute. Else authentication will fail.

The LdapAuth web API does not reveal in the authentication response what caused a login to fail – whether a wrong username, a wrong password, or both. To troubleshoot situations where a user is not able to login despite entering a correct username and password, check the service logs.

If a login was rejected due to a bad username, a line like this will appear in the log:

2012-10-01 10:52:51,460 INFO – user.auth: username=tom authenticated=false message=Invalid username

If the username was correctly resolved, but the password was bad:

2012-10-01 10:55:05,662 INFO – user.auth: username=alice DN=uid=alice,ou=people,dc=wonderland,dc=net authenticated=false message=Invalid password

If we have correctly resolved the user’s directory entry DN, we can proceed to the next step – checking the password.

Step 2 – Validating the user password

Passwords are checked by an LDAP command called bind. A connection is opened to the directory server, then a request is sent to authenticate the connection as a particular user entry by passing its entry DN and password:

DN: uid=alice,ou=people,dc=wonderland,dc=net
password: secret

If the credentials are correct, the directory server returns success. Else, it returns an LDAP error Invalid credentials (code 49).

Important things to note here:

  • The password is checked against an attribute in the user’s entry dedicated to serve that purpose. If you’re using a standard directory schema, this attribute is called userPassword. In MS Active Directory the name of this attribute is unicodePwd. Make sure that every user who is expected to login has a defined password attribute. Else authentication will fail.

  • The password values are often hashed and may be additionally protected, e.g. by making them write-only. Therefore a simple LDAP read and comparison will generally not work here. The bind command is always the preferred method.

  • Password are typically case sensitive.

Again, remember that log files are your friend. They record details of every login attempt and can be used for quick troubleshooting when authentication is not working as expected. If you need more help with configuring LdapAuth get in touch with us.