Search Filter Syntax

http://msdn.microsoft.com/en-us/library/aa746475%28VS.85%29.aspx

Search filters enable you to define search criteria and provide more efficient and effective searches.

ADSI supports the LDAP search filters as defined in RFC2254. These search filters are represented by Unicode strings. The following table lists some examples of LDAP search filters.

Search filterDescription"(objectClass=*)"All objects."(&(objectCategory=person)(objectClass=user)(!cn=andy))"All user objects but "andy"."(sn=sm*)"All objects with a surname that starts with "sm"."(&(objectCategory=person)(objectClass=contact)(|(sn=Smith)(sn=Johnson)))"All contacts with a surname equal to "Smith" or "Johnson".

 

These search filters use one of the following formats.

C++

<filter>=(<attribute><operator><value>)

or

C++

(<operator><filter1><filter2>)

The ADSI search filters are used in two ways. They form a part of the LDAP dialect for submitting queries through the OLE DB provider. They are also used with theIDirectorySearch interface.

Operators

The following table lists frequently used search filter operators.

Logical operatorDescription=Equal to~=Approximately equal to<=Lexicographically less than or equal to>=Lexicographically greater than or equal to&AND|OR!NOT

 

In addition to the operators above, LDAP defines two matching rule object identifiers (OIDs) that can be used to perform bitwise comparisons of numeric values. Matching rules have the following syntax.

C++

<attribute name>:<matching rule OID>:=<value>

"<attribute name>" is the lDAPDisplayName of the attribute, "<rule OID>" is the OID for the matching rule, and "<value>" is the value to use for comparison. Be aware that spaces cannot be used in this string. "<value>" must be a decimal number; it cannot be a hexadecimal number or a constant name such as ADS_GROUP_TYPE_SECURITY_ENABLED.

The following table lists the matching rule OIDs implemented by LDAP.

Matching rule OIDString identifier (from Ntldap.h)Description1.2.840.113556.1.4.803LDAP_MATCHING_RULE_BIT_ANDA match is found only if all bits from the attribute match the value. This rule is equivalent to a bitwiseAND operator.1.2.840.113556.1.4.804LDAP_MATCHING_RULE_BIT_ORA match is found if any bits from the attribute match the value. This rule is equivalent to a bitwiseOR operator.1.2.840.113556.1.4.1941LDAP_MATCHING_RULE_IN_CHAINThis rule is limited to filters that apply to the DN. This is a special "extended match operator that walks the chain of ancestry in objects all the way to the root until it finds a match.

 

The following example query string searches for group objects that have the ADS_GROUP_TYPE_SECURITY_ENABLED flag set. Be aware that the decimal value ofADS_GROUP_TYPE_SECURITY_ENABLED (0x80000000 = 2147483648) is used for the comparison value.

C++

(&(objectCategory=group)(groupType:1.2.840.113556.1.4.803:=2147483648))

The LDAP_MATCHING_RULE_IN_CHAIN is a matching rule OID that is designed to provide a method to look up the ancestry of an object. Many applications using AD and AD LDS usually work with hierarchical data, which is ordered by parent-child relationships. Previously, applications performed transitive group expansion to figure out group membership, which used too much network bandwidth; applications needed to make multiple roundtrips to figure out if an object fell "in the chain" if a link is traversed through to the end.

An example of such a query is one designed to check if a user "user1" is a member of group "group1". You would set the base to the user DN(cn=user1, cn=users, dc=x) and the scope to base, and use the following query.

C++

(memberof:1.2.840.113556.1.4.1941:=(cn=Group1,OU=groupsOU,DC=x))

Similarly, to find all the groups that "user1" is a member of, set the base to the groups container DN; for example(OU=groupsOU, dc=x) and the scope to subtree, and use the following filter.

C++

(member:1.2.840.113556.1.4.1941:=(cn=user1,cn=users,DC=x))

Note that when using LDAP_MATCHING_RULE_IN_CHAIN, scope is not limited—it can bebase, one-level, or subtree. Some such queries on subtrees may be more processor intensive, such as chasing links with a high fan-out; that is, listing all the groups that a user is a member of. Inefficient searches will log appropriate event log messages, as with any other type of query.

Wildcards

You can also add wildcards and conditions to an LDAP search filter. The following examples show substrings that can be used to search the directory.

Get all entries:

C++

(objectClass=*)

Get entries containing "bob" somewhere in the common name:

C++

(cn=*bob*)

Get entries with a common name greater than or equal to "bob":

C++

(cn>='bob')

Get all users with an email attribute:

C++

(&(objectClass=user)(email=*))

Get all user entries with an email attribute and a surname equal to "smith":

C++

(&(sn=smith)(objectClass=user)(email=*))

Get all user entries with a common name that starts with "andy", "steve", or "margaret":

C++

(&(objectClass=user)(| (cn=andy*)(cn=steve*)(cn=margaret*)))

Get all entries without an email attribute:

C++

(!(email=*))

The formal definition of the search filter is as follows (from RFC 1960):

C++

<filter> ::= '(' <filtercomp> ')'<filtercomp> ::= <and> | <or> | <not> | <item><and> ::= '&' <filterlist><or> ::= '|' <filterlist><not> ::= '!' <filter><filterlist> ::= <filter> | <filter> <filterlist><item> ::= <simple> | <present> | <substring><simple> ::= <attr> <filtertype> <value> <filtertype> ::= <equal> | <approx> | <ge> | <le><equal> ::= '='<approx> ::= '~='<ge> ::= '>='<le> ::= '<='<present> ::= <attr> '=*'<substring> ::= <attr> '=' <initial> <any> <final><initial> ::= NULL | <value><any> ::= '*' <starval><starval> ::= NULL | <value> '*' <starval><final> ::= NULL | <value>

The token <attr> is a string that represents an AttributeType. The token <value> is a string that represents an AttributeValue whose format is defined by the underlying directory service.

If a <value> must contain the asterisk (*), left parenthesis ((), or right parenthesis ()) character, the character should be preceded by the backslash escape character (\).

Special Characters

If any of the following special characters must appear in the search filter as literals, they must be replaced by the listed escape sequence.

ASCII characterEscape sequence substitute*\2a(\28)\29\\5cNUL\00/\2f

 

Note  In cases where a MultiByte Character Set is being used, the escape sequences listed above must be used if the search is performed by ADO with the SQL dialect.

In addition, arbitrary binary data may be represented by using the escape sequence syntax by encoding each byte of binary data with the backslash (\) followed by two hexadecimal digits. For example, the four-byte value 0x00000004 is encoded as \00\00\00\04 in a filter string.

Further Information

For more information, see:

• LDAP dialect
• SQL dialect
• Searching with the IDirectorySearch Interface
• Searching with ActiveX Data Objects
• Searching with OLE DB

 

 

Send comments about this topic to Microsoft

Build date: 10/26/2012

Community Additions

ADD

Filter for an OU

  
                              
  
    // Create a new DirectorySearcher that starts at the root.    // You can start it anywhere you want though    //     by providing a value in the DirectoryEntry constructor.    DirectorySearcher searcher = new DirectorySearcher(new DirectoryEntry()); // Set the scope to Subtree in order to search all children.searcher.SearchScope = SearchScope.Subtree; // Set the filter to only look for Organizational Units//     that have the name you are looking for.searcher.Filter = "(&(objectClass=organizationalUnit)(name=" + ouName + "))"; // If you are looking for only one result then do the following two things.SearchResult results = searcher.FindOne();this.Properties = results.GetDirectoryEntry();

Joshua Galloway

8/6/2012

Filter for an OU

  
    // Create a new DirectorySearcher that starts at the root.    // You can start it anywhere you want though    //     by providing a value in the DirectoryEntry constructor.    DirectorySearcher searcher = new DirectorySearcher(new DirectoryEntry()); // Set the scope to Subtree in order to search all children.searcher.SearchScope = SearchScope.Subtree; // Set the filter to only look for Organizational Units//     that have the name you are looking for.searcher.Filter = "(&(objectClass=organizationalUnit)(name=" + ouName + "))"; // If you are looking for only one result then do the following two things.SearchResult results = searcher.FindOne();this.Properties = results.GetDirectoryEntry();

Joshua Galloway

8/6/2012

Listing?

Is there a list of matching filters (e.g. LDAP_MATCHING_RULE_IN_CHAIN ) available anywhere?

bmcmcm

3/23/2012

SVN Authentication string

Hi,

I was using this string for SVN authentication which was working very quickly for authentication.

“ldap://10.36.53.14:389/OU=MW,OU=IT,OU=NewMedia,OU=Users,DC=local,DC=in?sAMAccountName?sub?(objectClass=*)”
***********************************************
now i m using this string for authenticate only group members instead of OU member, its working but authentication level is too much slow

“ldap://10.36.53.14:389/DC=local,DC=in?sAMAccountName?sub?(objectClass=user)(memberOf=CN=SVN-Access,OU=System Groups,DC=local,DC=in)”

Please help to resolve it thanks in advance

Salim Khan

Salimkhan350

12/8/2011

Apparent OR Error

This example is given in the text:

(&(objectClass=user) | (cn=andy*)(cn=steve*)(cn=margaret*))

I believe this is incorrect, and that it should be:

(&(objectClass=user) (|(cn=andy*)(cn=steve*)(cn=margaret*)))

Note added () enclosing the OR block.

Bill Denton - Pittsburgh, PA

9/23/2011

Fetch the records between the dates from LDAP

Hi,

I need to fetch the records between the dates(apr 30 2010-may 30 2010) from LDAP.So i used search filter as follows.

(&amp;(DateExpire&gt;=04302010)(DateExpire&lt;=05302010))";

But it is giving the records by executing both the conditions.Means it is giving the records greater than 30th apr 2010(like upto dec 31 2020) and also giving the records less than may 30 2010(like previous upto jan1 2004).

But my requirement is i need to fetch only the records between these given dates.Please suggest ways to do.


Thanks

[tfl] Thank you for your feedback. For these kinds of questions, please try the Microsoft forums:  http://social.answers.microsoft.com/Forums/en

Thomas Lee

9/4/2011

search excluding a group

Hello,

is it possible to query AD, all user BUT not the user of one particular group?

I try this:

(&(objectCategory=person)(objectClass=user)(!OU=CANCELED))

But it return an error: ldap.FILTER_ERROR: {'info': '', 'desc': 'Bad search filter'}

[tfl] Thank you for your feedback. For these kinds of questions, please try the Microsoft forums:  http://social.answers.microsoft.com/Forums/en

Thomas Lee

9/4/2011

How to search the Managers?

Hi,
I used the below query to find the managers list that starts with "man".

Query : (&;;(objectCategory=person)(objectClass=user)(|(manager=CN=man*)))

But I got "No items match the current search" message.

Need your help at the earliest.

Regards,

Partha

[tfl] Thank you for your feedback. For these kinds of questions, please try the Microsoft forums:  http://social.answers.microsoft.com/Forums/en

Thomas Lee

9/4/2011

IN_CHAIN EXAMPLE INCORRECT FILTER

Do not place the Parens () around the DN specified in the IN_CHAIN filter... It will not return the correct results

I.E. You want (memberof:1.2.840.113556.1.4.1941:=cn=Group1,OU=groupsOU,DC=x) not (memberof:1.2.840.113556.1.4.1941:=(cn=Group1,OU=groupsOU,DC=x))