LEX Online Manual Content

LDAP Filter Syntax

This topic deals with the syntax and rules for an LDAP filter, which is a normal string which expresses the criteria for the filter. You need knowledge about LDAP filters if you want to search objects and filter objects in the LDAP browser LEX.

You can get even more information about LDAP filters in the SelfADSI scripting Tutorial article about LDAP filters.

Basic LDAP Filter Syntax and Operators

LDAP filters consist of one or more criteria. If one than more criterion exist in one filter definition, they can be concatenated by logical AND or OR operators. The logical operators are always placed in front of the operands (i.e. the criteria). This is the so-called 'Polish Notation'.

The search criteria have to be put in parentheses and then the whole term has to be bracketed one more time.

AND Operation:

(& (...K1...) (...K2...)) or with more than two criteria: (& (...K1...) (...K2...) (...K3...) (...K4...))

OR Operation:

(| (...K1...) (...K2...)) or with more than two criteria: (| (...K1...) (...K2...) (...K3...) (...K4...))

Nested Operation:

Every AND/OR operation can also be understood as a single criterion:

(|(& (...K1...) (...K2...))(& (...K3...) (...K4...))) means: (K1 AND K2) OR (K3 AND K4)

The search criteria consist of a requirement for an LDAP attribute, e.g. (givenName=Sandra). Following rules should be considered:

Equality:	(attribute=abc) , e.g. (&(objectclass=user)(displayName=Foeckeler)
Negation:	(!(attribute=abc)) , e.g. (!objectClass=group)
Presence:	(attribute=) , e.g. (mailNickName=)
Absence:	(!(attribute=)) , e.g. (!proxyAddresses=)
Greater than:	(attribute>=abc) , e.g. (mdbStorageQuota>=100000)
Less than:	(attribute<=abc) , e.g. (mdbStorageQuota<=100000)
Proximity:	(attribute~=abc) , e.g. (displayName~=Foeckeler) Caution: ~= is treated as = in ADS environments !!
Wildcards:	e.g. (sn=F) or (mail=@cerrotorre.de) or (givenName=Paul)

Further rules:

Real attributes only

Only standard attributes can be used for LDAP filters. When specifying an LDAP search filter, you cannot use object properties of the ADSI objects that aren't LDAP database attributes but interface properties of the regarding object. A list of the affected properties can be viewed in the SelfADSI Scripting Tutorial under the topic 'Object Properties of ADSI Objects'.

No quotation marks

Comparative strings do NOT appear in quotation marks. A filter for the displayName 'Philipp Foeckeler' would read as follows: (displayName=Philipp Foeckeler).

Upper/lower case

If you want to filter boolean attributes the consideration of the upper/ lower case will be crucial. The use of TRUE or FALSE is absolutely necessary for filtering such booleans. However, most other string attributes are case-insensitiv, i.e. a hit will be found even if the upper and lower case differs from your search filter.

Especially in Exchange 5.5 directories most of the attributes are case sensitive. There are only few exceptions which can be viewed under the SelfADSI Scripting Tutorial topic 'Directory Attributes with CaseIgnoreString Syntax'.

DN-String attributes

Regarding match algorithms of LDAP filters, LDAP directory systems comply with the specifications of the original X.500 standards. According to these matching rules you can't use wildcards in LDAP filters for attributes containing LDAP distinguished names (attributes with DN-string syntax / ADSI attribute data type ADSTYPE_DN_STRING = 1). The same applies for ADS: Filters in which DN attributes are searched with wildcards do not work.

This can be quite irritating. You can't e.g. search for all users that are members in groups that contain a certain string in their group names. The reason for this is that the user attribute memberOf has the data type DN-string.

Even more important could be the search for objects in a specific OU. Especially, when only the declaration of a pure filter string is allowed and when there is no possibility to specify the search base of an LDAP search. This might well be so e.g. for the definition of recipient policies in Microsoft Exchange environments. Thus, the following filter won't work!

(distinguishedName=*,ou=Sydney,dc=cerrotorre,dc=org)

In this case we have to use a script-based solution which provides a workaround for this LDAP filter limitation.

Special characters

LDAP filters can be specified by unicode characters. You may, for example, use German umlauts - if it makes sense (if the filtered attribute is an unicode string). However, the characters ( ) & | = ! > < ~ * / \ play a special role for the declaration of LDAP filters.

If you search for or want to compare these characters within an attribute string, you'll have to use a prefixed backslash and the corresponding hexadecimal ASCII code:

(	\28	)	\29	&	\26
\|	\7c	=	\3d	>	\3e
<	\3c	~	\7e	*	\2a
/	\2f	\	\5c

An example: We want to retrieve all objects whose attributes "displayName" start with "*" :

(displayName=\2a)

The character zero (\00) may also be required occasionally.

Multivalued attributes....

It's also possible to filter for certain values in multivalue attributes. An example is the attribute objectClass. Due to the hierarchical structure of the directory schema, an object will always be an instance of several object classes. An ADS user e.g. is an object of the class types top, person, organizationalPerson und user. Thus, a filter could be:

(objectClass=user)

However, you need to take into consideration that such filtering always costs more server performance than an ordinary 'one-dimensional' attribute search does.

Filtering for Hex Numbers and Binary Values

Hex Numbers

In cases where attributes of the type integer or long integer are compared and filtered for specific hex numbers, the correspondent decimal coded number has always to be used in the LDAP filter. An example: If you look for local security groups in the ADS following two flags will have to be set for the groupType attribute:

ADS_GROUP_TYPE_LOCAL_GROUP (0x00000004)
ADS_GROUP_TYPE_SECURITY_ENABLED (0x80000000)

The addition of these values is the hex value 0x80000004, calculated in the decimal number 2147483652 - this has to be used in the LDAP filter:

(groupType=2147483652)

Binary Values

It's a completely different thing if you want to compose filters for attributes whose data types appear as binary hex values (the according data type is often referred to as 'Octet String').

If you are going to filter for such binary attributes, it is mandatory to declare every single byte that has to be compared in hex code. For instance, if you search for objects with the attribute 'Inventory' which has the value 0x01AAF5EF, then the appropriate filter will have to read:

(Inventory=\01\aa\f5\ef)

Unfortunately, wildcard search is not allowed when searching for binary attributes!

Filtering for Bit Fields

By using LDAP filters it's also possible to find objects for which a specific bit either is or is not set within a bit field. In this case, an strange looking syntax has to be followed:

There are exactly two BitFilterRule IDs: One for bit-wise AND comparisons and one for bit-wise OR comparisons:

LDAP_MATCHING_RULE_BIT_AND 1.2.840.113556.1.4.803
LDAP_MATCHING_RULE_BIT_OR 1.2.840.113556.1.4.804

An example:

For the attribute 'groupType' following bit mask is important in ADS group objects:

ADS_GROUP_TYPE_GLOBAL_GROUP     = 0x00000002
ADS_GROUP_TYPE_LOCAL_GROUP      = 0x00000004
ADS_GROUP_TYPE_UNIVERSAL_GROUP  = 0x00000008
ADS_GROUP_TYPE_SECURITY_ENABLED = 0x80000000

A filter for universal groups has to search for those objects in whose attributes the 4th least significant bit is set. This can be checked by equating the attribute of the value 0x00000008 (this represents the 4th bit) in an AND filter:

'All universal groups:

(groupType:1.2.840.113556.1.4.803:=8)

Caution: In LDAP filters the hex value of the bit filter must be decimal at this point! So if all security groups (and not the distribution groups) are to be found, it has to be filtered for the 8th bit (0x80000000 = 2147483648):

'All security enabled groups:

(groupType:1.2.840.113556.1.4.803:=2147483648)

An example for an OR filter: We search all users which don't need a password (userAccountControl is set on 0x20 - 32) or whose passwords never expires (userAccountControl is set on 0x10000 = 65536). So we have to build a filter with the value 65568 (=65536 + 32):

'All users which don't need a password OR whose passwords don't expire:

(userAccountControl:1.2.840.113556.1.4.804:=65568)

Please note that bit-wise filtering is a much more complex procedure for a server. For this reason you should take into consideration the use of normal equity criteria. If looking e.g. for universal security groups, the two flags 0x80000000 and 0x00000008 can be added up and then be filtered for the according decimal value 2147483656:

'All universal security groups:

(groupType=2147483656)

Please note that the LEX dialogs for editing LDAP Filters let's you set such bitmap filter syntaxes very easily.

Filtering with Ambiguous Name Resolution (ANR)

The Ambiguous Name Resolution is able to find users or contacts in Active Directory environments whose names are only partly known. In this case not only the object name but also the display name, first and last name as well as the diverse mail addresses are involved in the search. As an Outlook user you can have a look at the ANR filtering search by using e.g. the option 'Check names' for getting the best hit while searching for an address.

Which attributes are integrated exactly in the ANR search is specified by the attribute search flags in the directory schema. By doing so, a so-called ANR set of attributes is declared. Following attributes are part of the ANR set by default:

Relative Distinguished Name (RDN), this could be for example the values for cn=.... or ou=...
givenName (first name)
sn (last name)
displayName (display name)
legacyExchangeDN (after migrations the Exchange 5.5 directory name of the old mailbox is shown here)
proxyAddresses (mail addresses)
physicalDeliveryOfficeName (office address)

The syntax of ANR filters is as follows:

(anr=Philipp) or (anr=p f) or (anr=Foeck)

All these filters would find the user 'Foeckeler, Philipp'. The second one is able to find 'Philipp Foeckeler' as well as 'Fritz Paul'. This is because the ANR filter checks the first name and last name in both directions.