Skip to content
Tutorials Center
My learning

Topics

Lesson 10 of 38 ยท LDAP Protocol and Queries

LDAP Operations and Result Codes

Learn the LDAP protocol operations (bind, search, compare, add, modify, delete, modDN, unbind, extended), the message model and the result codes you will meet.

LDAP is a request and response protocol. A client connects to a server over TCP, sends numbered requests and reads responses. This lesson walks through every operation defined by RFC 4511, shows the typical flow of a session and teaches the result codes that tell you what went wrong.

You will not write the binary encoding by hand (it uses ASN.1 BER), but knowing the operations and codes lets you read logs, debug failing clients and understand every tool in this track. A Python stand-in at the end simulates a server and prints a typical session.

The operations

Operation Purpose Request carries
Bind Authenticate and set the identity for the connection DN and password, or a SASL mechanism
Unbind Close the session politely nothing
Search Find entries base DN, scope, filter, attributes, limits
Compare Test if an entry has a given attribute value DN, attribute, value
Add Create an entry DN and attributes
Modify Change attributes of an entry DN and a list of changes
Delete Remove a leaf entry DN
Modify DN Rename or move an entry DN, new RDN, new parent
Abandon Cancel an earlier request message ID
Extended Everything else: StartTLS, password modify, who am I OID and value

Responses to Search arrive as a stream: zero or more SearchResultEntry messages (one per matching entry), possibly SearchResultReference messages (referrals) and a final SearchResultDone containing the result code. All other operations get a single response.

A typical session

Connect TCP to 389, optional StartTLS.
Bind Authenticate as someone.
Operate Search, modify, add, delete.
Unbind Close the connection.

Each request has a message ID

1 / 2

Bind and authentication

Every connection starts anonymous. A Bind changes the identity. There are three families:

  1. Anonymous: empty DN and password.
  2. Simple: a DN (or, in Active Directory, a user principal name such as [email protected]) plus a password. The password travels as plain text, so you must protect the connection with TLS.
  3. SASL: pluggable mechanisms: EXTERNAL (client certificate), GSSAPI (Kerberos single sign-on), DIGEST-MD5 and SCRAM-SHA-256 on some servers. Active Directory commonly uses GSSAPI.

A subtle trap: an empty password with a non-empty DN is an unauthenticated bind. Many servers treat it as anonymous and return success, and applications that check only "bind succeeded" can wrongly accept anyone. Servers should disallow it, and your code must reject empty passwords before binding.

The most used operation. Its parameters are covered in Search Scope and Parameters and Filters. In short: where to start (base DN), how deep (scope), what to match (filter), what to return (attributes) and how much (size and time limits).

Compare

Compare answers "does this entry have this value?" with compareTrue (6) or compareFalse (5), without returning the data. It is handy for checking a group membership or a password hash without retrieving it:

Terminal
ldapcompare -x -D "cn=admin,dc=example,dc=com" -W \
  "cn=engineers,ou=Groups,dc=example,dc=com" "member:uid=asmith,ou=People,dc=example,dc=com"

Add, modify, delete, modify DN

These are the write operations. Each runs against one entry and is atomic per entry. There is no multi-entry transaction in standard LDAP, so a script that creates a user and then adds them to a group performs two independent operations; if the second fails, the first is not undone. You will practise them in Modifying Entries.

Extended operations and controls

LDAPv3 is extensible in two ways:

  • Extended operations add whole new requests identified by an OID: StartTLS (1.3.6.1.4.1.1466.20037) upgrades a plain connection to TLS, Password Modify (1.3.6.1.4.1.4203.1.11.1) changes a password and Who am I? (1.3.6.1.4.1.4203.1.11.3) returns your authorization identity.
  • Controls modify an existing operation: paged results, server-side sorting, and so on. See Controls and Paging.

Result codes

Every response carries a numeric result code, a matched DN (how much of the name was found) and an optional diagnostic message. Learn these:

Code Name Meaning
0 success The operation worked
1 operationsError Server problem or out-of-order request
2 protocolError Malformed request
3 timeLimitExceeded Search took too long
4 sizeLimitExceeded Too many results; you got a partial list
5 / 6 compareFalse / compareTrue Results of Compare
7 authMethodNotSupported Mechanism not allowed
8 strongerAuthRequired Use TLS or SASL
10 referral Ask another server
11 adminLimitExceeded A server limit was hit
13 confidentialityRequired Connection must be encrypted
16 noSuchAttribute Attribute not in the entry
17 undefinedAttributeType Attribute not in the schema
19 constraintViolation A rule such as password policy
20 attributeOrValueExists Duplicate value
21 invalidAttributeSyntax Value has the wrong format
32 noSuchObject The DN does not exist
34 invalidDNSyntax Malformed DN
48 inappropriateAuthentication e.g. password for an anonymous-only account
49 invalidCredentials Wrong DN or password
50 insufficientAccessRights Authenticated but not permitted
51 busy Try again later
53 unwillingToPerform Server refuses (for example, unencrypted password change)
64 namingViolation The RDN or parent is not allowed
65 objectClassViolation Entry breaks schema rules
66 notAllowedOnNonLeaf Entry has children
68 entryAlreadyExists The DN is already used

Active Directory adds detail in the diagnostic message, for example data 52e after code 49 means the password is wrong, data 775 means the account is locked out and data 532 that the password has expired.

A server session (Python stand-in)

This model is a tiny in-memory server. It is not LDAP on the wire; it only shows the sequence of operations and the codes you would see. Note how the unauthenticated bind is handled.

Python Simulated session with result codes

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Another useful habit is to map codes to remedies. The helper below groups codes into the three kinds of problem that decide who must act: the client, the data, or the server.

Python Which side is at fault?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which result code means the credentials were wrong?

    49 is invalidCredentials. 50 means you are authenticated but not allowed; 32 means the object does not exist.
  2. 2. Why is a bind with a DN but an empty password dangerous?

    Applications must reject empty passwords themselves, since an unauthenticated bind may succeed.
  3. 3. Is a script that adds a user and then adds them to a group a single transaction in standard LDAP?

    Standard LDAP has no multi-entry transactions, so design for partial failure.
  4. 4. Which extended operation upgrades a plain LDAP connection to TLS?

    StartTLS is an extended operation identified by OID 1.3.6.1.4.1.1466.20037.

Summary

  • LDAP is request and response; the main operations are bind, search, compare, add, modify, delete, modify DN, unbind, abandon and extended.
  • Binds authenticate anonymously, with a password or through SASL (GSSAPI, EXTERNAL). Always use TLS for passwords and reject empty passwords yourself.
  • Writes are atomic per entry only; there are no multi-entry transactions.
  • Extended operations and controls extend the protocol: StartTLS, Password Modify, paging and more.
  • Memorize the common result codes: 0, 32, 49, 50, 53, 65, 68.

Next: LDAP Search Filters