SelfADSI - The LDAP / ADSI Scripting Tutorial
LDAP Filter

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)

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*)

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 under the topic 'Object Properties of ADSI Objects'.

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 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 contaning 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. I've carried out one of many possible alternatives: FAQ - Setting addresses of recipients for all users of a specific OU via script (German FAQ).

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:

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

   (displayName=\2a*)

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

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.

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 mnumber 2147483652 - this has to be used in the LDAP filter:

   (groupType=2147483652)

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!

Usually, Octet String attributes are difficult to read out by 0 VBScript and thus have to be converted into a more manageable data type. The accordant procedures can be learnt in the SelfADSI article 'Directory Attributes of type Octet String'.

(groupType:1.2.840.113556.1.4.803:=8)                    ' All universal groups

(groupType:1.2.840.113556.1.4.803:=2147483648)           ' All security enabled groups

(groupType=2147483656)                                  ' All universal security groups

Alle Users:

    (&(objectCategory=person)(objectClass=user))

All Groups:

    (objectClass=group)

All Contacts:

    (&(objectCategory=person)(objectClass=contact))

All security groups (local, global and universal):

    (groupType:1.2.840.113556.1.4.803:=2147483648)

All users with the account configuration 'Password never expires':

    (&(objectCategory=person)(objectClass=user)(userAccountControl:1.2.840.113556.1.4.803:=65536))

All users with mailboxes on Exchange server 'KUNGUR':

    (msExchangeHomeserverName=
    /o=MAILOrg/ou=First Administrative Group/cn=Configuration/cn=Servers/cn=KUNGUR)

All users whose account is disabled:

    (&(objectCategory=person)(objectClass=user)(userAccountControl:1.2.840.113556.1.4.803:=2))

All hidden Exchange mail recipients:

    (msExchHideFromAddressLists=TRUE)

All hidden Exchange mail recipients (without public folder objects):

    (&(msExchHideFromAddressLists=TRUE)(!objectClass=publicFolder))

All hidden mail recipients with fax adress:

    (proxyAddresses=FAX:*)

All mailboxes:

    (objectClass=organizationalPerson)

All distribution lists:

    (objectClass=groupOfNames)

All custom recipients:

    (objectClass=Remote-Address)

All mailboxes of the server 'TRANGO' in site 'Site1' in the organisation 'MAIL':

    (Home-MTA=cn=Microsoft MTA,cn=TRANGO,cn=Servers,cn=Configuration,ou=Site1,o=MAIL=Remote-Address)"

All hidden Exchange mail recipients (requires authentication as 'cn=USER,dc=DOM,cn=admin'):

    (Hide-From-Address-Book=TRUE)"

All recipients whose display name starts with 'F':

    (cn=F*)