Browse learn

LDAP Filter Matching Rules

Understand how LDAP matching rules define equality, ordering, substring, and extensible comparisons and why server schemas determine query behavior.

Type
Reference
Level
Advanced
Technologies
LDAP
On this page

What Are LDAP Filter Matching Rules?

LDAP filter matching rules define the logic for comparing attribute values in directory search filters. Every filter—whether it's a simple equality check or an advanced recursive group search—uses a matching rule to determine if a directory entry satisfies its criteria. These rules specify how attribute values should be compared: for exact matches, ordering, patterns, approximate similarity, or through custom, extensible methods. Matching rules can be standard (implied by filter operators and attribute type) or explicitly specified using extensible filter syntax and a matching rule identifier such as an OID (Object Identifier).

Matching rules are central to LDAP's searching flexibility. For example, a filter like (sn=Smith) uses the surname's default equality matching rule. By extending the syntax, you can use rules that perform case-insensitive comparisons, evaluate values in distinguished names (DNs), or even execute bitwise operations. Understanding matching rules empowers developers to construct precise and powerful LDAP queries and to troubleshoot mismatched or ineffective filters.

Types of LDAP Matching Rules

LDAP defines several standard matching rule types, each supporting a different filtering need:

Equality Matching Rules

An equality matching rule tests if an attribute's value matches the filter assertion exactly, using logic appropriate to the attribute's syntax. For example, (uid=alice) returns entries where uid is exactly alice. This is the most common matching rule and is typically implied whenever you use the = operator.

Ordering Matching Rules

Ordering matching rules compare values for greater-than or less-than relationships. These apply only to orderable attributes like integers or certain timestamps. For example, (age>=30) filters for entries with an age attribute greater than or equal to 30. If you specify an ordering matching rule where the attribute does not support ordering, the server will return an error.

Substring Matching Rules

Substring matching enables searches for patterns using wildcards, typically the asterisk (*). For instance, (sn=Sm*) matches entries whose surname starts with "Sm". Substring rules are only available for attribute syntaxes that support them (often directory string types).

Approximate Matching Rules

Approximate matching rules, accessible via the ~= operator (e.g., (cn~=Jon)), are intended to return entries whose attribute value "resembles" the given value—such as through soundex or edit-distance logic. Actual behavior and support for approximate matching vary by server and attribute.

Extensible Matching Rules

Extensible matching rules provide a way to specify exactly which matching logic (by name or OID) should be used for evaluating an attribute in a filter. This allows developers to invoke vendor-specific logic, perform bitwise comparisons, or execute sophisticated matching over structured attributes. The extensible syntax is required for these use cases.

Extensible Match Filters and OIDs

Extensible match filters unlock advanced query features by allowing explicit selection of the matching rule. The syntax for an extensible match filter is:

text
(attribute[:dn][:matchingRule]:=value)
  • attribute: The attribute to evaluate.
  • :dn: Optional. If specified, matches are made against the attribute's presence in the DN rather than in the entry's attribute values.
  • :matchingRule: Optional. May be a name or, more universally, an OID. Selects the matching logic to apply.
  • :=: Indicates extensible match; must be used in this filter form.
  • value: The assertion value to compare.

OIDs: Identifying Matching Rules

Matching rules are most precisely identified by OID, a numeric identifier registered in the directory schema. For example, Active Directory's bitwise AND matching rule uses OID 1.2.840.113556.1.4.803. Using an OID ensures the correct logic is invoked, even when names are ambiguous or unsupported.

DN Component Matching

Specifying :dn targets the DN's components rather than the entry's attribute values. For example, (ou:dn:=Sales) matches any entry whose DN has an OU=Sales component. When using :dn without a matching rule, the default equality rule for the attribute applies.

Component and Bitwise Matching

Some advanced rules—like component matching (OID 2.5.13.33)—allow assertion against subfields of structured attributes or complex application logic. The ability to reference these rules depends on schema support and server implementation.

Practical Examples of Matching Rule Filters

  • Standard equality via extensible syntax:
    (sn:=Smith)
    (Matches surname using default equality rule.)

  • DN component matching:
    (ou:dn:=Sales)
    (Matches entries with an OU of Sales in their DN.)

  • Matching rule by OID (e.g., bitwise AND in AD):
    (userAccountControl:1.2.840.113556.1.4.803:=2)
    (Matches entries where the bit flag 2 is set.)

  • Recursive group membership in AD:
    (memberOf:1.2.840.113556.1.4.1941:=CN=Group,DC=example,DC=com)
    (Returns members, direct or nested, of the specified group.)

  • Substring match:
    (sn=Sm*)
    (Surname begins with "Sm".)

  • Component matching over structured attributes:
    (compoundAttribute:2.5.13.33:=componentFilter...)
    (Requires server and schema support.)

Where to Find Matching Rule OIDs and Server Support

Matching rule OIDs are found in the LDAP server’s schema, accessible via the subschema subentry, and are documented in RFCs and server-specific materials. Common sources include:

  • Directory Schema: The server’s schema definitions enumerate available matching rules with their OIDs and applicable attributes.
  • RFCs: Standard rules and their OIDs are described in documents like RFC 4515 and RFC 3687.
  • Vendor Documentation: Servers such as Active Directory document proprietary rule OIDs, especially for extensions like bitwise or recursive matching.

Before using a matching rule OID, confirm server support—some rules exist only in certain vendors' directories or only for specific attributes. Attempting a filter with an unsupported matching rule will generally result in an error or empty result.

Caveats, Errors, and Cross-Platform Considerations

Several issues can arise when working with LDAP filter matching rules:

  • Unsupported Matching Rules: Not all servers support all matching rules, particularly extensible, bitwise, or component rules. Filters using unsupported OIDs will fail.
  • Attribute-Type Mismatches: Using an ordering rule on an attribute without ordering support (e.g., strings) or a DN-matching filter against a non-DN attribute will return errors or ignore the assertion.
  • Vendor-Specific Logic: Matching rules like bitwise operations (1.2.840.113556.1.4.803) or recursive group membership (1.2.840.113556.1.4.1941) are present in Active Directory but not necessarily elsewhere.
  • :dn Modifier Restrictions: The :dn modifier operates only on attributes present in the DN. Filters like (mail:dn:=foo@example.com) will have no effect unless mail is encoded as a DN component.
  • Omitting Matching Rule or OID: When no matching rule is specified, the server defaults to the attribute's schema-defined rule. Explicit OIDs are only required for alternate or advanced logic.
  • Differences in Filter Syntax Support: While RFC 4515 standardizes filter string representation, servers may vary slightly in their extensions or error handling.

Sources

Related resources