LDAP Filter Syntax

Why LDAP Filter Syntax Matters

LDAP filter syntax defines how searches are expressed in directory servers like OpenLDAP and Active Directory. Understanding this syntax is essential for anyone who needs to precisely retrieve entries, enforce security, or avoid operational failures. Filters are not forgiving: a small syntax error or logical mistake leads to incorrect searches, empty results, or even security exposures.

A valid simple filter:

(cn=John Smith)

But robust, real-world LDAP queries require more than basic matching. Correct handling of nested filters, wildcards, and special character escaping is crucial.

Core Structure of LDAP Filters

LDAP filters use a strict, parenthesized, operator-first grammar—also called “Polish notation.” Every filter clause is enclosed in parentheses, and logical operators always appear before their operands.

Examples of base structures:

• Equality: (attribute=value)
• Logical AND: (&(clause1)(clause2))
• Logical OR: (|(clause1)(clause2))
• Logical NOT: (!(clause))

Filters can be nested to any depth, as long as every operand is itself a complete filter in parentheses.

Example: Nested Logic

Find all users in the "Engineering" department whose account is enabled:

(&(department=Engineering)(accountStatus=enabled))

Negate a condition—for instance, users who are not in "Contractor":

(!(department=Contractor))

Operators and Filter Types: The Building Blocks

LDAP filters support a defined set of match and logical operators as mandated by the standard (RFC 4515).

Match Operators

• Equality: (attribute=value) — Matches if the attribute’s value equals the specified value.
• Presence: (attribute=*) — Matches if the attribute exists in the entry.
• Comparison:
  • Greater or Equal: (attribute>=value)
  • Less or Equal: (attribute<=value)
• Approximate: (attribute~=value) — Tests for "equality with some fuzziness." Rarely implemented or reliable; don’t rely on it for portable filters.

Substring Filters: Structure and Rules

Substring filters allow pattern matching using the * wildcard within the value. Placement of wildcards is strictly controlled by the filter grammar.

General form (from RFC 4515 BNF):

(attribute=initial*sub1*sub2*...*final)

• initial: optional string that must appear at the start.
• Each subN: substring that must appear, in order, anywhere after initial and before final.
• final: optional string that must appear at the end.

Key rules:

• Wildcards (*) separate required substrings—they represent “any zero or more characters.”
• No two wildcard asterisks can be adjacent (** is invalid).
• You may omit initial or final (or both).
• Escape literal * with \2a if the attribute value itself includes an asterisk.

Table: Valid Substring Filter Patterns (per RFC 4515)

Visual of substring filter structure (RFC 4515):

• Initial only: (cn=prefix*)
• Final only: (cn=*suffix)
• Initial and final: (cn=prefix*suffix)
• Contains/embedded: (cn=*substring*)
• With multiple required substrings in order: (cn=prefix*sub1*sub2*suffix)

Clarifying Example: Suffix and Contains

• (mail=*user@example.com) — Matches an address ending with user@example.com (anything may precede).
• (mail=*example.com*) — Matches any address containing example.com anywhere, not just at the end.

Escaping Wildcard and Special Characters in Substrings

If you need to search for the literal *, escape it as \2a, even within substrings:

(cn=abc\2a*)

Matches attribute values that start with abc* literally, followed by anything.

Extensible Match

Advanced filters can specify alternative matching rules by OID, or apply to the DN:

(attribute:1.2.840.113556.1.4.803:=value)

These are used for rare scenarios or certain server-specific tasks, especially in Active Directory.

Boolean Logic and Nesting: Combining Filter Clauses

LDAP’s logical operators combine filters using prefix (Polish) notation. Every operand must itself be a complete, parenthesized filter.

• AND: & — All subfilters must match
• OR: | — At least one subfilter must match
• NOT: ! — Must not match the subfilter

Syntax Examples

Find entries that are “user” objects and have accountEnabled=TRUE:

(&(objectClass=user)(accountEnabled=TRUE))

Find entries whose surname is “Smith” or “Johnson”:

(|(sn=Smith)(sn=Johnson))

Exclude results where status is “disabled”:

(!(accountStatus=disabled))

Complex Nesting

Combine logic using nested operators:

(&
  (accountEnabled=TRUE)
  (!(department=Contractor))
)

Find users enabled and not in the Contractor department.

(&
  (|(department=Engineering)(department=Sales))
  (!(l=London))
)

Find users in Engineering or Sales departments, excluding those based in London.

Important: Always enclose each operand filter in its own parentheses; infix logic (SQL-style) is not allowed.

Escaping Special Characters in LDAP Filter Values

Certain characters must be escaped within LDAP filter values because they have structural meaning in filters. This is done by using a single backslash (\) followed by the two-digit hexadecimal code for the character’s byte value. Both uppercase and lowercase hex digits are valid per RFC 4515.

Characters That Must Be Escaped

• Escaping must be done at the byte level.
• Both uppercase (\2A) and lowercase (\2a) hex digits are accepted.

Example: Escaping Usage

Filter for the exact value “Dev*(Test)” in the cn attribute:

(cn=Dev\2a\28Test\29)

Filter for a value beginning with a literal asterisk:

(cn=\2aLead)

Escaping works identically within substrings:

(cn=abc\2a*)   // matches "abc*" followed by any string

Failure to escape special characters leads to filter errors or unintended matches.

Case Sensitivity and Attribute Matching Nuances

LDAP filter matching is controlled by the schema-defined matching rules of each attribute:

• Standard string attributes are usually case-insensitive. For example, both (cn=John) and (cn=john) generally match the same entry.
• Boolean values stored as strings are commonly case-insensitive, but always consult your schema and product documentation for edge cases.
• Numeric attributes: Greater/less than filters compare using lexicographic (string) ordering, not numerical value, unless otherwise specified.
• DN-valued attributes: Distinguished Name matching is always case-insensitive.

Always check the schema documentation for exact matching behavior.

Common LDAP Filter Mistakes (and How to Fix Them)

Negation and "Not Equals"

• Mistake: (cn!=John)
• Correction: Use NOT as a logical operator with a nested filter: (!(cn=John))

Quoting Strings

• Mistake: (sn="Smith")
• Correction: Never use quotes: (sn=Smith)

Presence Filter

• Mistake: (mail)
• Correction: Presence is always (mail=*)

Wildcard Placement in Substrings

• Mistake: Misplaced or double wildcards, e.g., (cn=**John**)
• Correction: Wildcards only separate substrings and are not doubled; see the table above.

Substring Misconceptions

• Mistake: Interpreting (mail=*@example.com) as matching “@example.com” anywhere in value.
• Correction: This matches values ending with “@example.com” (any prefix), not those just containing it. For a true "contains" filter, use: (mail=*example.com*).

Logic Operators

• Mistake: Writing filters as in SQL: ((department=HR) OR (department=Sales))
• Correction: Use prefix notation: (|(department=HR)(department=Sales))

Search Scope vs Attribute Value

• Mistake: Using (ou=Engineering) to find users in a specific OU.
• Correction: That matches the ou attribute, not an entry’s location. LDAP filters only inspect attribute values, not entry DNs or tree location. Use the search base to define scope, not the filter itself.

LDAP Filter Syntax vs SQL Queries: Key Differences

Example: Users named John or Jane

• LDAP: (|(cn=John)(cn=Jane))
• SQL: WHERE cn = 'John' OR cn = 'Jane'

SQL and LDAP filters look related but have different structure and semantics—direct translation is not possible.

Advanced and Vendor-Specific Features

Extensible Matches

An extensible filter can specify a matching rule (by OID) or target the entry DN:

(member:1.2.840.113556.1.4.1941:=cn=Alice,ou=Users,dc=example,dc=com)

Primarily seen in advanced Active Directory scenarios (e.g., recursive group searches).

Active Directory Extensions

Operators for bitwise matching and the "in-chain" OID are specific to Active Directory servers and are not portable.

Always verify that any such feature exists and is supported on your target platform.

Best Practices and Troubleshooting Tips

• Test on realistic data, building complexity stepwise.
• Escape all special characters in dynamic or user input—*, (, ), \, and NUL.
• Avoid broad filters like (objectClass=*) to prevent performance overloads.
• Document complex/nested filters for code clarity and stability.
• Be wary of performance: filters with broad wildcards or large OR lists are slow unless attributes are indexed.
• Consult schema documentation to clarify attribute behavior and case sensitivity.

Example: Restricting to a Specific OU

Set your search base to the DN of the OU, such as ou=Engineering,dc=example,dc=com, and use filters for attributes only:

• Search base: ou=Engineering,dc=example,dc=com
• Filter: (&(objectClass=user)(!(accountStatus=disabled)))

LDAP filters never describe a directory path—only attribute values. Tree scoping is always configured via the search base, not via attribute filters.

By applying these principles, LDAP filter use becomes safer, more predictable, and aligned with directory standards and operational best practices.

Sources

• www.rfc-editor.org — rfc4515
• www.rfc-editor.org — rfc4516
• www.rfc-editor.org — rfc2254