BackendBench
Coffee

Unravel โ€บ Java concepts โ€บ Security

Spring

LDAP and directory lookups

LDAP (and Active Directory) is the company address book that stores users, groups and credentials.

๐Ÿ”Ž Unravel this example

At a glance

Mental model

The staff directory in a building lobby: a tree of departments and people.

What happens, in order
  1. 1Entries live in a tree identified by a distinguished name (DN) such as uid=ana,ou=people,dc=acme,dc=comAttributes hold values (cn, mail, memberOf).
  2. 2Authentication is a bind: connect as the user with their passwordSpring Security's BindAuthenticator does a search for the user DN first (with a service account) and then binds as that user.
  3. 3Search with a base DN, a filter such as (&(objectClass=person)(uid=ana)) and a scopeLdapTemplate.search(query, attributesMapper) maps results to Java objects.
  4. 4Group mapping converts LDAP groups to Spring authorities (ROLE_ADMIN)
Remember
Watch out
Concatenating user input into filtersAccepting empty passwordsCleartext ldap://No timeouts on directory calls
Example (highlighted lines explain it)
List<String> names = ldapTemplate.search(    LdapQueryBuilder.query().base("ou=people").where("objectClass").is("person").and("uid").is(username),    (AttributesMapper<String>) attrs -> (String) attrs.get("cn").get());
  1. line 2 uses LdapQueryBuilder, the core of LDAP and directory lookups
  2. line 3 uses AttributesMapper, the core of LDAP and directory lookups
Read the full explanation (about 1 min)

LDAP (and Active Directory) is the company address book that stores users, groups and credentials. Applications use it to log people in and to read their group memberships.

A mental model

The staff directory in a building lobby: a tree of departments and people. You ask "which people in engineering have the role admin" and it answers; you can also check someone secret at the door.

How it works

Entries live in a tree identified by a distinguished name (DN) such as uid=ana,ou=people,dc=acme,dc=com. Attributes hold values (cn, mail, memberOf).

Authentication is a bind: connect as the user with their password. Spring Security's BindAuthenticator does a search for the user DN first (with a service account) and then binds as that user.

Search with a base DN, a filter such as (&(objectClass=person)(uid=ana)) and a scope. LdapTemplate.search(query, attributesMapper) maps results to Java objects.

Group mapping converts LDAP groups to Spring authorities (ROLE_ADMIN).

Going deeper

Never build filters by concatenating user input; special characters (*, (, ), \) allow LDAP injection. Use LdapQueryBuilder or LdapEncoder.filterEncode.

An empty password in a bind request is treated as an anonymous bind by many servers, and "succeeds". Reject empty passwords before calling LDAP.

Use LDAPS or StartTLS; plain ldap:// sends passwords in clear text. Connection pooling and timeouts matter, as directories are shared and slow under load.

Under the hood

JNDI (InitialDirContext) and Spring LDAP both speak the LDAP protocol over a TCP connection: a bind operation sets the identity of the connection, then search and compare requests are sent as ASN.1 encoded messages, each answered with entries and a result code.

Common mistakes

  • Concatenating user input into filters.
  • Accepting empty passwords.
  • Cleartext ldap://.
  • No timeouts on directory calls.

How Unravel recognises it

When you paste code, Unravel looks for these signs of ldap and directory lookups. Spotting them yourself is a good habit when you read unfamiliar code:

Part of a learning path

Related concepts

Spring Security basicsSpringPassword hashing (BCrypt, Argon2, PBKDF2)Spring

Frequently asked questions

What is LDAP and directory lookups?

LDAP (and Active Directory) is the company address book that stores users, groups and credentials. Applications use it to log people in and to read their group memberships.

What are the most common mistakes with LDAP and directory lookups?

Concatenating user input into filters. Accepting empty passwords. Cleartext ldap://. No timeouts on directory calls.

How can I see LDAP and directory lookups in real code?

Paste your own Java into Unravel and it will point out where ldap and directory lookups appears, explain how it works at the detail level you choose, and draw the flow of the code around it.