LDAP Syntax filters can be used in many situations to query Active Directory. They can be used in VBScript and PowerShell scripts. Many utilities, like adfind and dsquery *, accept LDAP filters. Many PowerShell Active Directory module cmdlets, like Get-ADUser, Get-ADGroup, Get-ADComputer, and Get-ADObject, accept LDAP filters with the LDAPFilter parameter.
A filter specifies the conditions that must be met for a record to be included in the recordset (or collection) that results from a query. An LDAP filter has one or more clauses, each enclosed in parentheses. Each clause evaluates to either True or False. An LDAP syntax filter clause is in the following form:
(<AD Attribute><comparison operator><value>)
The <AD Attribute> must the the LDAP Display name of an Active Directory attribute. The allowed comparison operators are as follows:
Note that the operators "<" and ">" are not supported. Another operator, ~= (which means approximately equal to) is supported, but no case has been found where this is useful in Active Directory. The <value> in a clause will be the actual value of the Active Directory attribute. The value is not case sensitive and should not be quoted. The wildcard character "*" is allowed, except when the <AD Attribute> is a DN attribute. Examples of DN attributes are distinguishedName, manager, directReports, member, and memberOf. If the attribute is DN, then only the equality operator is allowed and you must specify the full distinguished name for the value (or the "*" character for all objects with any value for the attribute). Do not enclose the DN value in parentheses (as is done erroneously in some documentation). If the attribute is multi-valued, then the condition is met if any of the values in the attribute match the filter. An example LDAP syntax filter clause is:
(cn=Jim Smith)
This filters on all objects where the value of the cn attribute (the common name of the object) is equal to the string "Jim Smith" (not case sensitive). Filter clauses can be combined using the following operators:
For example, the following specifies that either the cn attribute must be "Jim Smith", or the givenName attribute must be "Jim" and the sn attribute must be "Smith":
(|(cn=Jim Smith)(&(givenName=Jim)(sn=Smith)))
Conditions can be nested with parentheses, but make sure the parentheses match up.
↑ Return to Top
The LDAP filter specification assigns special meaning to the following characters:
* ( ) \ NUL
The NUL character is ASCII 00. In LDAP filters these 5 characters should be escaped with the backslash escape character, followed by the two character ASCII hexadecimal representation of the character. The following table documents this:
For example, to find all objects where the common name is "James Jim*) Smith", the LDAP filter would be:
(cn=James Jim\2A\29 Smith)
Actually, the parentheses only need to be escaped if they are unmatched, as above. If instead the common name were "James (Jim) Smith", nothing would need to be escaped. However, any characters, including non-display and foreign characters, can be escaped in a similar manner in an LDAP filter. For example, here are a few foreign characters:
When your filter clause includes the objectCategory attribute, LDAP does some magic to convert the values for your convenience. The objectCategory attribute is a DN attribute. A typical value for an object in Active Directory might be "cn=person,cn=Schema,cn=Configuration,dc=MyDomain,dc=com". You can use a filter clause similar to the following:
(objectCategory=cn=person,cn=Schema,cn=Configuration,dc=MyDomain,dc=com)
However, Active Directory allows you to instead use the following shortcut:
(objectCategory=person)
The following table documents the result of various combinations of clauses specifying values for objectCategory and objectClass:
Use the filter that makes your intent most clear. Also, if you have a choice between using objectCategory and objectClass, it is recommended that you use objectCategory. That is because objectCategory is both single valued and indexed, while objectClass is multi-valued and not indexed (except on Windows Server 2008 and above). A query using a filter with objectCategory will be more efficient than a similar filter with objectClass. Windows Server 2008 domain controllers (and above) have a special behavior that indexes the objectClass attribute. You can take advantage of this if all of your domain controllers are Windows Server 2008, or if you specify a Windows Server 2008 domain controller in your query.
The following table shows many example LDAP filters that can be useful when you query Active Directory:
You can use the following PowerShell V1 script to test various LDAP syntax filters in your environment: Generic Search of Active Directory: http://gallery.technet.microsoft.com/Generic-Search-of-Active-0a05b8d0
This article is based on the following page: http://www.rlmueller.net/ADOSearchTips.htm. Search Filter Syntax: http://msdn.microsoft.com/en-us/library/aa746475%28v=VS.85%29.aspx Ambiguous Name Resolution: http://www.rlmueller.net/AmbiguousNameResolution.htm How Active Directory Searches Work: http://technet.microsoft.com/en-us/library/cc755809%28v=ws.10%29.aspx ↑ Return to Top
This article is also available in the following languages: Russian (ru-RU)
TNJMAN edited Revision 73. Comment: minor touch-up editing
Richard Mueller edited Revision 69. Comment: Added example finding object by the first 8 bytes of objectGUID
Richard Mueller edited Revision 68. Comment: Added filter for confidential attributes
Richard Mueller edited Revision 67. Comment: Added filter for RODC_FILTERED attributes
Richard Mueller edited Revision 66. Comment: Added link to PowerShell V1 script to test LDAP syntax filters
Richard Mueller edited Revision 65. Comment: Added filter for objects with disallow delete
Richard Mueller edited Revision 64. Comment: Added filter for indexed attributes in schema
Richard Mueller edited Revision 63. Comment: Added filter for attributes preserved in tombstone objects
Richard Mueller edited Revision 62. Comment: Added filter for attributes in ANR set
Richard Mueller edited Revision 61. Comment: Added filter for attributes whose values are copied when an object is copied