Skip to content
Connect2id

LDAP user authentication explained

LDAP user authentication validates a user’s credentials against a directory such as Microsoft Active Directory, OpenLDAP or OpenDJ. LDAP directories store user and group information and make it available to applications.

A common authentication flow has two steps: resolve the identifier entered by the user to a directory entry, then ask the directory to validate the password. This article explains that flow and how to configure it in LdapAuth.

Step 1 – Resolve the username to a directory DN

An LDAP entry is identified by a distinguished name (DN). A user DN might look like this:

uid=alice,ou=people,dc=wonderland,dc=net

The user usually enters a username or email address rather than a DN. LdapAuth must resolve that identifier to the user’s directory entry before it can authenticate using the entry’s DN.

One way to do this is to search the directory for an entry whose identifying attribute matches the supplied value. The attributes searched are specified by the search filter. In the default configuration, LdapAuth searches the uid and mail attributes. The %u placeholder represents the identifier supplied by the user:

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

To search only by uid:

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

To include an employee number:

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

When configuring DN resolution, check that:

  • Each permitted login identifier identifies only one user. If a search finds multiple matching entries, LdapAuth cannot determine which account to authenticate.
  • Every user has the attribute they are expected to use at login. For example, users who sign in with an email address need a mail value.

LdapAuth also supports resolving a DN from a configured template when the directory’s DN structure permits it.

Authentication responses do not distinguish a wrong username from a wrong password. If a user cannot sign in, inspect the LdapAuth logs. For example, a failed attempt may identify either a username that could not be resolved:

user.auth: username=tom authenticated=false message=Invalid username

or a resolved user whose password was rejected:

user.auth: username=alice DN=uid=alice,ou=people,dc=wonderland,dc=net authenticated=false message=Invalid password

Step 2 – Validate the password with a bind

Once LdapAuth has resolved the user’s DN, it performs an LDAP bind using that DN and the password supplied by the user:

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

The directory validates the credentials and returns a bind result. Invalid credentials commonly produce LDAP result code 49 (invalidCredentials); other failures can produce different result codes. LdapAuth does not need to read the user’s stored password or compare password values itself.

Use StartTLS or LDAPS to protect the password in transit. An empty password must not be treated as a successful user login: in LDAP simple bind, a DN accompanied by an empty password can request unauthenticated access.

Passwords are normally case-sensitive. If authentication fails despite a correctly resolved DN, check the service logs and the directory’s account status and password policy. For help configuring LdapAuth, contact us.