What Are LDAP Substring Filters?

Updated on April 15, 2025

This article is a complete guide to LDAP substring filters. It explains what they are, how they work, their syntax with examples, common use cases, limitations, and more.

What Are LDAP Substring Filters?

LDAP substring filters are search tools used within an LDAP directory to match parts of an attribute’s value. Unlike equality filters that require exact matches, substring filters allow partial matches, making them ideal for searches based on incomplete data.

The substring filter syntax looks like this:

(attribute=value)

However, when substring filters are used, value can include one or more wildcards designated by asterisks *. These wildcards allow flexible searching by indicating parts of a string that can vary or remain unknown.

Key Concepts in Substring Filters

• subInitial: Refers to a substring that must appear at the beginning of the attribute’s value. Example syntax: (cn=John*)
  • This matches all entries where the “common name” starts with “John.”
• subAny: Represents one or more substrings that can appear anywhere within the attribute’s value. Example syntax: (cn=John)
  • This matches entries where “John” appears anywhere in the “common name.”
• subFinal: Refers to a substring that must appear at the end of the attribute’s value. Example syntax: (sn=*son)
  • This matches entries where the “surname” ends with “son.”

Why Use Substring Filters?

LDAP substring filters are particularly valuable when dealing with partial or incomplete data. Whether you’re troubleshooting user accounts, filtering specific files, or searching based on partial names or email addresses, substring filters provide the flexibility needed for more targeted searches.

How Substring Filters Work

When an LDAP substring filter is applied, the LDAP server performs a systematic search:

1. The server examines the specified attribute for each entry within the search scope.
2. It checks whether the attribute’s value matches the substring filter conditions, with the wildcards used as flexible placeholders.
3. If the attribute’s value satisfies all criteria (e.g., starting with X, containing Y, and ending with Z), the entry is included in the search results.

This process is efficient for narrowing down search results from thousands (or even millions) of directory entries, making administrative tasks far more manageable.

Syntax Details and Examples

Let’s look at the practical application of LDAP substring filters through some common examples.

• Finding users whose common name starts with “John”
  • Syntax: (cn=John*)
    • Matches entries where the cn (common name) starts with the exact substring “John.”
• Finding users whose surname ends with “son”
  • Syntax: (sn=*son)
    • Retrieves entries where the sn (surname) ends with the substring “son.”
• Finding users whose email contains “example”
  • Syntax: (mail=example)
    • Matches any entry where the mail (email address) contains “example” anywhere in the string.
• Finding users whose common name contains “John” and “Doe” in any order
  • Syntax: (cn=JohnDoe*)
    • Matches entries where the cn contains both “John” and “Doe” with any characters between them.
• Combining subInitial, subAny, and subFinal
  • Syntax: (cn=Jn D)
    • Matches names that start with “J,” contain “n D,” and can end with anything.

Each example demonstrates how substring filters offer versatility when exact matches would fall short.

While LDAP substring filters are powerful, they are not without limitations.

Efficiency Concerns

Excessive wildcard usage can lead to performance inefficiencies, especially when working with large directories. For example, using multiple * wildcards in a single query can significantly slow down the search process.

Attribute Support

Substring filters are typically effective for string-based attributes. Certain attribute types may not support substring searches, depending on your LDAP server implementation.

Complex Matching

Substring filters are limited in their ability to perform complex logical conditions (e.g., “startswith A and endswith B but excludes C”). For such cases, combining multiple filter types may be necessary.

Use Cases for Substring Filters

Now, let’s explore five scenarios where LDAP substring filters prove particularly valuable:

1. Name Searches: Quickly find users when you only know part of their name (e.g., searching for all users whose name starts with “Alex”).
2. Email Filtering: Extract all entries with email addresses from a specific domain (e.g., (mail=*example.com)).
3. Description or Notes Matching: Retrieve entries containing specific keywords in description fields (e.g., (description=Manager)).
4. File or URL Filtering: Locate entries storing file paths, domain names, or other patterns (e.g., (url=https)).
5. Implementing “Starts With,” “Ends With,” or “Contains” Functionality: Enable user-friendly directory searches in web applications or internal tools by leveraging substring filters for partial matches.

Comparison with Equality Filters

It’s important to distinguish substring filters from equality filters:

• Equality Filter
  • Syntax example: (cn=John Doe)
    • This retrieves entries where the exact value of the cn attribute is “John Doe.” No flexibility is allowed.
• Substring Filter:
  • Syntax example: (cn=John*)
    • On the other hand, substring filters allow matches based on partial values, making them more adaptable in scenarios where the full attribute value isn’t known.

While equality filters provide precision, substring filters excel at flexibility.

Key Terms Appendix

• LDAP (Lightweight Directory Access Protocol): A protocol for accessing and managing directory information. 
• Filter: A criterion used to retrieve entries in an LDAP directory. 
• Attribute: A property of an LDAP entry, such as “name” or “email.” 
• Substring: A portion of a string value. 
• Wildcard: The * character used to represent zero or more characters in a string. 
• subInitial: The substring that must appear at the beginning of the value. 
• subAny: Substrings that may appear anywhere in the value. 
• subFinal: The substring that must appear at the end of the value.