How LDAP Works, Message by Message

An application that "logs users in with LDAP" runs a short, fixed conversation with the directory: upgrade the connection to TLS, bind as a service account, search for the user's entry, bind again as that entry with the password the user typed, and read the result code. Every step is an LDAPMessage from RFC 4511. This page walks through each one with fake values, ties every field to its RFC section, and lists the checks the application must run. For what LDAP is and where it fits, see the LDAP standard page.

The sequence at a glance

Many applications use LDAPS on port 636 instead of step 1; the messages after the TLS handshake are identical.

The envelope every message shares

LDAPMessage ::= SEQUENCE {
     messageID       MessageID,          -- INTEGER, chosen by the client
     protocolOp      CHOICE { bindRequest, bindResponse, searchRequest, ... },
     controls        [0] Controls OPTIONAL }

messageID is unique per outstanding request and is how responses are matched to requests on a pipelined connection (§4.1.1–4.1.1.1). Everything is BER-encoded ASN.1 (§5.1); the examples below are decoded into readable form.

Step 1: StartTLS

messageID 1
extendedReq { requestName "1.3.6.1.4.1.1466.20037" }      -- no requestValue

messageID 1
extendedResp { resultCode success (0), matchedDN "", diagnosticMessage "",
               responseName "1.3.6.1.4.1.1466.20037" }

After a success response the client starts the TLS handshake on the same connection. It must then check the server's identity against the certificate as RFC 4513 §3.1.3 describes, and RFC 4511 §6 advises clients to reject referrals returned by the StartTLS operation. A client that falls back to cleartext when StartTLS fails has no protection against an attacker who simply blocks it.

Step 2: bind as the service account

messageID 2
bindRequest {
  version        3,
  name           "cn=svc-portal,ou=service,dc=example,dc=com",
  authentication simple "not-a-real-password-example" }

messageID 2
bindResponse { resultCode success (0), matchedDN "", diagnosticMessage "" }

SASL EXTERNAL with a client certificate, or GSSAPI with a Kerberos keytab, removes the service account password altogether.

Step 3: find the user

The command-line equivalent with OpenLDAP's ldapsearch:

ldapsearch -ZZ -H ldap://dc1.example.com \
  -D "cn=svc-portal,ou=service,dc=example,dc=com" -W \
  -b "ou=people,dc=example,dc=com" -s sub -z 2 \
  "(&(objectClass=person)(uid=ada))" dn uid mail entryUUID

On the wire:

messageID 3
searchRequest {
  baseObject   "ou=people,dc=example,dc=com",
  scope        wholeSubtree (2),
  derefAliases neverDerefAliases (0),
  sizeLimit    2,
  timeLimit    10,
  typesOnly    FALSE,
  filter       and { equalityMatch { objectClass, "person" },
                     equalityMatch { uid, "ada" } },
  attributes   [ "uid", "mail", "entryUUID" ] }

messageID 3
searchResEntry {
  objectName "uid=ada,ou=people,dc=example,dc=com",
  attributes [ uid: "ada", mail: "ada@example.com",
               entryUUID: "597ae2f6-16a6-1027-98f4-abcdefabcdef" ] }

messageID 3
searchResDone { resultCode success (0), matchedDN "", diagnosticMessage "" }

Step 4: bind as the user

messageID 4
bindRequest { version 3, name "uid=ada,ou=people,dc=example,dc=com",
              authentication simple "<the password the user typed>" }

messageID 4
bindResponse { resultCode invalidCredentials (49), matchedDN "",
               diagnosticMessage "" }

Result 49 means the DN is valid syntax but the credentials are not (RFC 4513 §5.1.3). Return the same error to the user whether the account does not exist or the password is wrong; diagnosticMessage and differing result codes can reveal which, a disclosure RFC 4511 §6 warns about.

Do this bind on a separate connection, or rebind as the service account afterwards: the bind changes the connection's authorization state (RFC 4513 §4), and any later group lookup would run with the user's rights.

The checks an LDAP-authenticating application must run

1. TLS first, verified. Complete StartTLS or LDAPS and validate the server certificate and name before any bind (RFC 4513 §3.1.3; RFC 4511 §6). Never fall back to cleartext.
2. Reject empty passwords before sending the bind. An empty password turns a simple bind into the unauthenticated mechanism, which authenticates nobody (RFC 4513 §5.1.2, §6.3.1).
3. Escape every user-supplied value: filter values per RFC 4515 §3 (* → \2a, ( → \28, ) → \29, \ → \5c, NUL → \00) and DN values per RFC 4514 §2.4.
4. Exactly one entry. Treat zero or more than one search result as a failed login, not "use the first".
5. Success means resultCode 0 on the user bind, nothing else (RFC 4511 §4.1.9). Do not infer success from the absence of an exception.
6. Do not follow referrals with credentials to servers you did not configure (RFC 4511 §6, §4.1.10).
7. Key accounts on a stable identifier (entryUUID or objectGUID), not uid, mail or the DN, which change on rename or move.
8. Least-privilege service account: read-only, scoped to the subtrees the application needs, with a rotated credential or SASL EXTERNAL/GSSAPI instead of a password.

Common implementation mistakes, with the CVEs behind them

Try it locally

SWI has no browser tool for LDAP, because a browser cannot open raw TCP connections. Use OpenLDAP's ldapsearch against a test directory: -ZZ requires StartTLS to succeed, -d 1 prints protocol debugging, and binding with -w "" shows how your server answers an unauthenticated bind. If it returns success, fix the server configuration before an application relies on it.

Related

LDAP standard page, how Kerberos works, message by message, how RADIUS works, message by message, SCIM message flow. Glossary: LDAP, directory service, Active Directory.