LdapAuth articles

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.

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.

LdapAuth 2.3 with user realm identification

Posted on 2012-08-22

LdapAuth 2.3 adds a new realm.get call to identify the user base for which an LdapAuth instance provides authentication and details provisioning. This call is intended to enable future versions of our OpenID Connect server to handle multiple user realms at once.

The realm name is optional and is set by the ldapAuth.authRealm configuration parameter.

To retrieve the realm name of a particular LdapAuth instance make a realm.get call as described in the web API manual.

Here is an example response identifying the user realm as wonderland.net:

{ "result"  : "wonderland.net",
  "id"      : 1,
  "jsonrpc" : "2.0"

If no realm is configured the result will be an empty string.

LdapAuth 2.2 with API key and failover support

Posted on 2012-08-10

Just before the summer break we released LdapAuth 2.2, the embeddable Connect2id product for simple user authentication and provisioning over the web using JSON-RPC 2.0.

The new version introduces support for API key access control as well as specifying multiple backend LDAP servers for failover and load-balancing purposes.

API keys

API keys is a popular method for controlling client access to a web service. LdapAuth 2.2 enables administrators to specify a set of API keys to grant access to selected methods, such as user.auth and user.get. Other methods meant for public use or methods that don’t carry sensitive information may be exempted from the API key requirement.

The API keys complement the previous available access control choices based on whitelisted client IPs, HTTPS security and X.509 client certificates.

LDAP server failover + load-balancing

LdapAuth enables customers to take advantage of replicated LDAP backends, for the purpose of LDAP server failover or load-balancing.

If you specify an LDAP server set you can choose between two server selection modes – failover and round-robin:

  1. Select FAILOVER to instruct LdapAuth to attempt to establish connections to the LDAP servers in the order they are provided. If the first server is unavailable, then it will attempt to connect to the second, then to the third and so on.

  2. Select ROUND-ROBIN to instruct LdapAuth to use a round-robin algorithm to select the LDAP server to which the connection should be established. Any number of servers may be included in the set and earch request will attempt to retrieve a connection to the next server in the list, circling back to the beginning of the list as necessary. If a server is unavailable when an attempt is made to establish a connection to it, then the connection will be established to the next available server in the list.

The connect timeout setting enables you to specify the precise timeout in milliseconds for LDAP connect requests. If zero LdapAuth will default to a suitable timeout value.

You can download an evaluation copy of LdapAuth from our product downloads page. No registration is required for that.