Connectors
Active Directory V2
Common Documentation
Active Directory V1

Active Directory LDAP Paths and Filters

You can connect to AD using LDAP paths and filters.

LDAP Path

The LDAP Path to your Active Directory can be a full LDAP path or server name.

If you want to use just the server name your connection would look similar to: LDAP://dc01

Otherwise examples of full LDAP Paths are:

  • You can connect to your global OU by omitting any OU's from the path, note that you will need your domain controller name to be listed: LDAP://dc01/dc=demo,dc=simego,dc=com

  • You can connect to a specific OU by adding the OU to the path, note that you will need your domain controller name to be listed: LDAP://dc01/OU=Test,DC=demo,DC=simego,DC=com

Locate LDAP Path

If you are struggling to find your LDAP Path you can use ADSI Edit to help you. Locate your OU within ADSI Edit, right click onto your OU and select properties.

ADSI Edit

Then find the distinguished name attribute in the list and this will give you the Path to that OU.

LDAP Path

LDAP Filter

You can use an LDAP Filter to limit the results returned from Active Directory.

The default filter is set as (&(objectClass=User)(givenname=*)(sn=*)) this returns Active Directory Objects that are of type user have a givenname value and a sn value.

LDAP Filter Syntax

Retrieve Computers

It is possible to retrieve computers by setting the LDAP Filter property to return just the Computer objects:

(&(objectClass=Computer))

Group Filter

The LDAP filter below is an example filter that returns users that are members of the CRM Team Users Active Directory group

(&(objectClass=User)(memberOf=CN=CRM Team Users,CN=Users,DC=corp,DC=litware,DC=inc))

Password Never Expires

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

Filter Types

Presence Filters

These are used to determine if an entry contains at least one value for that particular attribute.

An example of a presence filter that would return entries that contains one or more cn values would be (cn=*). Or to return all entries, as entries must have at least one objectClass value the presence filter would be (objectClass=*).

Equality Filters

These are similar to presence filters, in that if the entry includes the specified value then it will match the filter for that value.

This filter can be used to return entries of a certain name, however as there is usually multiple ways a name could be presented (e.g. Sally, sally, SALLY, SallY etc.) you will need an equality matching tile to determine if the values are equivalent.

Examples of matching rules can be:

  • caseIgnoreMatch (OID 2.5.13.2) which will match two strings if they differ due to capitalisation or insignificant spaces.
  • caseExactMatch (OID 2.5.13.5) which considers capitalisation to be significant, and will match two strings if they differ only in insignificant spaces.

So to include the caseIgnoreMatch matching rule in your filter you could write:

(givenName:2.5.13.2:=Sally)

You can read more on matching rules here.

Greater or Equal Filters

This filter is used to determine if an entry contains a value that is greater than or equal to the one supplied in the filter. An ordering matching rule will be used to make the determination. The syntax for this filter is:

(attributeName>=value)

If an entry has one or more values for the attribute that are greater than or equal to the target value it will return true, even if it has other values that are determined to be less than the target.

An example of how this can be used is when filtering LastLogon values:

(&(objectCategory=person)(objectClass=user)(lastLogon>=20110301000000.0Z))

or users that changed their password since 15 April 2011:

(&(objectCategory=person)(objectClass=user)(pwdLastSet>=129473172000000000))

Less or Equal Filters

This filter is used to determine if an entry contains a value that is less than or equal to the one supplied in the filter. An ordering matching rule will be used to make the determination. The syntax for this filter is:

(attributeName<=value)

If an entry has one or more values for the attribute that are less than or equal to the target value it will return true, even if it has other values that are determined to be greater than the target.

An example of how this can be used is when filtering LastLogon values:

(&(objectCategory=person)(objectClass=user)(lastLogon<=20110301000000.0Z))

or users that last changed their password before 15 April 2011:

(&(objectCategory=person)(objectClass=user)(pwdLastSet<=129473172000000000))

Substring Filters

This can be used to determine if an entry contains at least one value that matches the filter. Matching rules are used to determine is an attribute value matches the substring.

The syntax for this filter is:

(attributeName=subInitial*subAny*subAny*subFinal)

A substring filter must have at least one subInitial, subAny or subFinal component. You do not need to have one of each. Examples of these are:

(cn=Liz*) has a subInitial of "Liz" but no subAny or subFinal components.

(cn=*Liz*) has a subAny of "Liz" but no subInital or subFinal components.

(cn=*Smith) has a subFinal of "Smith" but no subInitial or SubAny components.

Extensible Match Filters

These are more complex than other filters. You may wish to use an extensible match filter to override the default matching rule, to determine if a value exists in any attribute, or to determine if a value exists in the attributes used to make the distinguished name for the entry.

The syntax for this filter is: (attributeName:dn:matchingRule:=value)

There are a few options available for this filter, examples of these can be seen here:

(givenName:=Liz) this can be used to see if the entry contains a givenName with the value "Liz".

(givenName:dn:=Liz) this can be used to see if the entry or its distinguished name contains a givenName with the value "Liz".

(givenName:caseExactMatch:=Liz) this can be used to see if the entry contains a givenName with the value "Liz" using the case-exact matching.

(givenName:dn:2.5.13.5:=Liz) this can be used to see if the entry or its distinguished name has a givenName attribute of "Liz" using the matching rule with OID 2.5.13.5.

(:caseExactMatch:=Liz) this can be used to see if the entry contains any attribute with the value "Liz" using the case-exact matching.

(:dn:2.5.13.5:=Liz) this can be used to see if the entry or its distinguished name contains any attribute with the value "Liz" using the matching rule with OID 2.5.13.5.

AND Filters

An AND filter will only return true if all the filters it encapsulate evaluate to true. This filter is constructed with the following syntax (&(filterOne)(filterTwo))

An example to match the given name and a surname is:

(&(givenName=Jane)(sn=Doe))

The AND filter rules are:

  • You can have any number of components in an AND filter.
  • Any AND filter that has a component that evaluates to undefined will never return true.
  • An AND filter that has at least one component that evaluates false will return false.
  • An AND filter that has one or more components that evaluate to undefined and zero will return undefined. This is treated as logically equivalent to false.

OR Filters

An OR filter will only return true if at least one of the filters it encapsulates evaluates to true.

This filter is constructed with the following syntax: (|(filterOne)(filterTwo)(filterThree))

An example to match multiple given names is: (|(givenName=Liz)(givenName=Elizabeth)(givenName=Beth))

An OR filter does not need to encapsulate components, (|), and when it does not encapsulate components it is known as the false filter as it will never amtch any entry.

The OR Filter rules are:

  • It is better to have one OR filter with lots of components rather than nesting many OR filters.
  • Any OR filter that one or more components that evaluate to undefined will never return false.
  • Any OR filter that has at least one component that evaluates to true will return true.
  • Any OR filter that has every component evaluating to false will return false.

NOT Filters

The NOT filter is used alongside another filter, such as equals, OR, AND etc. It negates the result of that filter being used.

It is constructed with the following syntax: (!(filterCondition)).

For example (!(givenName=Liz)) will return entries that do not match givenName=Liz.

However if an entry has multiple givenName values, such as Liz and Elizabeth, it will still return the entry. This is because Elizabeth does not meet the condition to be excluded even though the Liz givenName does. You would need to use an extensible match filter with a custom matching rule to exclude all entries that have givenName=Liz even if there are alternative givenName values.

String Representation

Certain characters will be required to be escaped in order to be used within the LDAP Filter. The escape sequence will vary depending on the character being escaped. Below you will find the rules for some of the most common characters:

  • ( must be escaped as \28
  • ) must be escaped as \29
  • * must be escaped as \2a
  • \ must be escaped as \5c
  • Nul must be escaped as \00

Escaping removes the chance for ambiguity, for example if you want to return any entry your can use the asterisk (*) as a wildcard e.g. (cn=*). However if you want to return values that contain an asterisk you would need to use the escape sequence e.g. (cn=\2a)

Special Characters

  • á must be escaped as \e1
  • é must be escaped as \e9
  • í must be escaped as \ed
  • ó must be escaped as \f3
  • ú must be escaped as \fa
  • ñ must be escaped as \f1