Skip to content
Tutorials Center
My learning

Topics

Lesson 11 of 38 ยท LDAP Protocol and Queries

LDAP Search Filters

Master LDAP filter syntax: equality, presence, substring, ordering, approximate, AND/OR/NOT in prefix notation, extensible match and escaping per RFC 4515.

A search filter tells the server which entries to return. LDAP filters look unusual: they use prefix notation with parentheses, so AND and OR come before their operands. Once you can read them, you can query any directory. This lesson covers every filter type, how to combine them, escaping rules (a security topic) and Active Directory examples.

At the end you will run a real filter parser and evaluator written in Python as a stand-in, so you can test filters against a small directory in your browser.

Simple filters

Every filter is wrapped in parentheses and compares an attribute with a value:

Type Syntax Example Meaning
Equality (attr=value) (uid=asmith) Value equals, under the attribute's matching rule
Presence (attr=*) (mail=*) The attribute exists
Substring (attr=a*b*c) (cn=Ali*Smi*) Initial, any and final parts
Greater or equal (attr>=value) (uidNumber>=1000) Ordering rule required
Less or equal (attr<=value) (uidNumber<=2000)
Approximate (attr~=value) (sn~=smyth) "Sounds like"; server dependent
Extensible (attr:rule:=value) (cn:caseExactMatch:=Alice) A named matching rule

There is no > or < alone; only >= and <=. To express "greater than 1000" with integers, write (uidNumber>=1001), or (&(uidNumber>=1000)(!(uidNumber=1000))).

Combining filters

Three operators combine filters, placed before the operands:

  • (&(f1)(f2)(f3)) is AND: all must match.
  • (|(f1)(f2)) is OR: at least one matches.
  • (!(f)) is NOT: negates one filter.

Examples:

TEXT
(&(objectClass=inetOrgPerson)(mail=*))
(|(uid=asmith)(uid=bjones))
(&(objectClass=person)(!(telephoneNumber=*)))
(&(objectClass=person)(|(ou=Engineering)(ou=Support))(!(title=Intern)))

The last one reads: "persons whose department is Engineering or Support, who are not interns". Use consistent indentation when writing long filters in scripts:

TEXT
(&
  (objectClass=person)
  (|
    (ou=Engineering)
    (ou=Support))
  (!(title=Intern)))

Filter operators

AND (&(a)(b)) all must match.
OR (|(a)(b)) any may match.
NOT (!(a)) negate one filter.

Operator first, operands after

1 / 2

Escaping special characters

Inside a filter value, five characters must be escaped as a backslash plus two hex digits (RFC 4515):

Character Escape
* \2a
( \28
) \29
\ \5c
NUL \00

Note this is different from DN escaping, which uses \, forms. A search for a user named A*B (Test) becomes (cn=A\2aB \28Test\29).

If your application builds filters by pasting user input, a user who types *)(uid=*))(|(uid=* can rewrite your query. This is LDAP injection. Always escape user-supplied values with your library's function (for example ldap3.utils.conv.escape_filter_chars) and validate input before searching.

Case and matching

Whether (cn=alice smith) matches Alice Smith depends on the attribute's matching rule. In most directories cn, uid, mail and sn ignore case. Substring matches (*) also use the attribute's substring rule. Binary and numeric attributes need their own rules (integerMatch, octetStringMatch).

Active Directory filters

AD uses LDAP filters but adds attributes and matching rules you will use constantly:

Goal Filter
All users (&(objectCategory=person)(objectClass=user))
User by logon name (sAMAccountName=asmith)
Disabled accounts (&(objectClass=user)(userAccountControl:1.2.840.113556.1.4.803:=2))
Enabled accounts (&(objectClass=user)(!(userAccountControl:1.2.840.113556.1.4.803:=2)))
Members of a group, including nested groups (memberOf:1.2.840.113556.1.4.1941:=CN=Admins,OU=Groups,DC=corp,DC=example,DC=test)
Computers (objectClass=computer)
Accounts that never expire (accountExpires=9223372036854775807)

The OIDs are matching rules: ...4.803 is a bitwise AND, used with the bit flags of userAccountControl (bit value 2 means disabled); ...4.1941 is LDAP_MATCHING_RULE_IN_CHAIN, which follows group nesting. You will see these again in Users, Computers and Groups.

Performance tips

  • Prefer indexed attributes (objectClass, uid, cn, mail, sAMAccountName in AD).
  • Put the most selective test first in an AND. Servers may reorder, but not all do.
  • Avoid leading wildcards ((cn=*smith)); they cannot use ordinary indexes.
  • Avoid NOT on large sets: (!(attr=value)) forces the server to read everything.
  • Ask only for the attributes you need.

Parse and evaluate filters (Python stand-in)

The first stand-in is a recursive parser for RFC 4515 filters (equality, presence, substring, >=, <=, AND, OR, NOT). The second block runs it against a small in-memory directory. Matching here is case-insensitive for simplicity.

Python LDAP filter parser and matcher

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 how the final test finds dstar: the escapes \2a, \28 and \29 stand for the literal characters in the name.

Building filters safely

The helper below shows the right way to insert user text: escape first, then format. It also demonstrates what happens without escaping.

Python Escape user input before building a filter

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 filter finds persons who have a mail attribute but are not interns?

    LDAP has no != operator. Negate with (!(...)) and put AND first in prefix notation.
  2. 2. How do you search for a literal asterisk in a value?

    RFC 4515 filter escaping uses a backslash followed by two hex digits; * is \2a.
  3. 3. What does (uidNumber>=1000) require to work properly with numbers?

    Ordering comparisons depend on the attribute's ordering rule; text attributes compare as strings.
  4. 4. In Active Directory, which part of a filter follows group nesting?

    LDAP_MATCHING_RULE_IN_CHAIN (โ€ฆ4.1941) evaluates nested group membership.

Summary

  • Filters are parenthesized and use prefix operators: &, |, !.
  • Types: equality, presence (=*), substring, >=, <=, approximate and extensible match.
  • Escape *, (, ), \ and NUL as \2a, \28, \29, \5c, \00 to avoid LDAP injection.
  • Active Directory uses bitwise and in-chain matching rules for flags and nested groups.
  • Prefer indexed attributes, avoid leading wildcards and heavy NOT filters.

Next: Search Scope and Parameters