Browse learn

What Is an LDAP Filter?

Learn how LDAP filters select directory entries, how filter expressions are structured, and where clients use them in search operations.

Type
Concept
Level
Beginner
Technologies
LDAP
On this page

What Is an LDAP Filter?

An LDAP filter is a logical expression—represented as a specially formatted string—that defines criteria for selecting directory entries in LDAP (Lightweight Directory Access Protocol) searches. Standardized by RFC 4515, an LDAP filter allows applications and users to precisely narrow results returned by a directory server, such as when searching for users, groups, or other objects. Each filter expresses conditions on entry attributes, and only entries that satisfy the filter are included in the search results.

In practical terms, LDAP filters are used wherever LDAP queries are performed: in authentication workflows, identity provisioning, access management scripts, custom applications, and administrative tools. For example, an application might use a filter to locate a user by their username: (uid=bjensen) or to find all entries with an email attribute: (mail=*).

LDAP Filter Syntax: String Representation

LDAP filter strings follow a parenthesized, prefix notation as mandated by RFC 4515. Each filter starts and ends with parentheses, and logical operators are nested within, enabling complex combinations of basic tests.

Core syntax:

  • Each filter is enclosed in parentheses: (filter)
  • Attribute assertions are formatted as (attribute=Value)
  • Logical operators precede their operands and group filters with parentheses:
    • AND: (& (filter1) (filter2) ...)
    • OR: (| (filter1) (filter2) ...)
    • NOT: (! (filter))

Examples:

  • Find users with a username of "alice": (uid=alice)
  • Find entries with an email address: (mail=*)
  • Find users named "bob" who are members of "group1": (& (cn=bob) (memberOf=group1))
  • Negate a condition (users not with a given title): (!(title=Manager))

Parentheses and logical prefixes allow filters to express complex, nested conditions, which are evaluated server-side by the LDAP service.

Operators and Filter Types

LDAP filters support several types of assertions and logical operators, defined by the protocol standards and directory schema in use.

Core Filter Types:

  • Equality Match: (attribute=value)
    Returns entries where the attribute exactly matches the value.

  • Presence Filter: (attribute=*)
    Matches entries where the attribute exists (regardless of value).

  • Substring Filter: (attribute=val*), (attribute=*val), or (attribute=*val*)
    Finds entries where the attribute starts with, ends with, or contains a substring.

  • Ordering Match:

    • Greater or equal: (attribute>=value)
    • Less or equal: (attribute<=value)
      Operator support depends on attribute syntax and matching rules.

  • Approximate Match: (attribute~=value)
    Matches entries approximately equal to the value; interpretation is schema-specific.

  • Logical Operators:

    • AND: (& (filter1)(filter2)... ) (All conditions must match)
    • OR: (| (filter1)(filter2)... ) (At least one matches)
    • NOT: (! (filter)) (Negate a filter)

  • Extensible Match (optional, schema-dependent):
    Syntax: (<attribute>:<matchingRuleOID>:<dn>:=<value>)
    Used for applying specific matching rules; support varies and is generally advanced.

  • Absolute True/False (RFC 4526):

    • Always true: (&)
    • Always false: (|)
      Many servers (including Active Directory) support this extension.

Wildcard and Special Character Handling

The * symbol is special:

  • In substring filters, * acts as a wildcard for zero or more characters: (cn=J*hn)
  • In presence filters, * stands alone: (mail=*)

If a literal * is needed in the value part, it must be escaped using a backslash and its hexadecimal value (e.g., \2a). Other characters requiring escaping include ( (\28), ) (\29), \ (\5c), and NUL (\00).

Example Filters

  • Basic equality: (sAMAccountName=jdoe)
  • Presence: (objectClass=*)
  • Substring: (displayName=*Smith*)
  • AND combination: (&(objectClass=user)(department=Engineering))
  • NOT filter: (!(mail=*))

LDAP Filters vs. SQL Queries: Key Differences

Despite a superficial resemblance between LDAP filters and SQL WHERE clauses, there are fundamental differences:

  • Syntax and Logic:
    LDAP filters use prefix notation, strict parenthesized expressions, and lack infix operators. SQL uses infix notation and a different operator set.

  • Data Model:
    LDAP operates on a hierarchical (tree-structured) set of entries and attribute-value pairs; SQL queries tables with columns and rows.

  • Capabilities:
    LDAP filters can only reference attributes of a single entry at a time. SQL WHERE clauses support joins, aggregations, subqueries, and richer data operations.

  • Matching Rules:
    LDAP filter evaluation depends on the schema-defined matching rules for each attribute, including case sensitivity and equality rules. SQL often uses standard type-based comparison logic.

  • Server Evaluation:
    LDAP filters are evaluated server-side, always on the directory's current state; SQL queries can include computed columns and functions.

  • Portability:
    While basic filters are broadly portable, advanced LDAP filter features or matching rules (such as extensible matches or vendor-specific OIDs) may not be compatible across all LDAP servers.

Attempting to translate SQL queries directly to LDAP filters usually leads to incorrect or incomplete results due to these differences.

Practical Applications and Risks

Applications

LDAP filters are foundational wherever directories are searched or queried:

  • User authentication lookups (e.g., finding a user account matching a login name)
  • Group membership enumeration
  • Directory synchronization and user/group import scripts
  • Administrative queries in tools or PowerShell
  • Search filters in LDAP URLs
  • Attribute-based access controls in identity applications

Filters are provided as part of search operations (as required by RFC 4511) and are always parsed and executed by the LDAP server, not on the client.

Common Troubleshooting Scenarios

  • Unexpected empty results: Misconstructed filter, case/whitespace issues, or unmatched attribute type.
  • Erroneous matches: Incorrect wildcard use or unescaped special characters.
  • Server error or rejection: Invalid filter syntax or use of unsupported filter types.

Security Considerations

LDAP filter injection is a risk when untrusted input (e.g., usernames, email addresses) is interpolated directly into filter strings without proper escaping. An attacker could manipulate the filter logic to modify query results, bypass restrictions, or exfiltrate data.

Mitigation:
Always escape special characters per RFC 4515 when incorporating external input into filters:

  • Replace * ( ) \ and NUL (\0) with their backslash hexadecimal representation (e.g., * as \2a).

Vendor and Schema-Specific Extensions

Some servers, particularly Active Directory, support additional matching rules (e.g., OID-based extensible matching) or specific evaluation behaviors. While the basic filter syntax is consistent, test advanced filters and matching rules on your target directory to confirm support.

References: Official LDAP Filter Standards

  • RFC 4515: LDAP: String Representation of Search Filters
  • RFC 4511: Lightweight Directory Access Protocol (LDAP): The Protocol
  • RFC 4526: LDAP Absolute True and False Filters

Sources

Related resources