Defining LDAP Search Criteria

 

References to Web policy content are only available when a Web Gateway is included in the peer group.

This topic provides background information on how to specify search criteria when defining LDAP Synchronized User Name or Email Address Lists.

Target DN for Sync

The Target DN for Sync identifies the Distinguished Name of the base node from which you wish to start your search.

An LDAP directory is arranged in a tree structure, with nodes usually in the following top-down order:

+ root

   + countries

      + organizations

          + organizational units

              - individuals

When viewing the tree, you can expand each node to reveal any additional nodes beneath it.

This diagram shows an example tree structure for individual users in the Sales department of "Your Company plc", based in the UK. Each node is represented by a rectangle:

This diagram shows an example tree structure for individual email users in the Sales department of "Your Company plc", based in the UK. Each node is represented by a rectangle:

Example LDAP tree structure

Each node can be uniquely identified using its Distinguished Name (DN). This is formed from the names of all the nodes listed sequentially, starting from the node you are identifying, up to the top of the tree. For example, the Distinguished Name of the node containing Vince or Vince's email address is:

cn=Vince, ou=Sales, o=Your Company plc, c=UK

Nodes contain data in the form of one or more attribute=value pairs. For example, in the diagram above, each cn (common name) node contains an attribute. Every node usually contains at least one ObjectClass attribute (not shown).

Scope

The scope determines the area of the tree to include in the search. You can specify one of the following:

Filter

The filter you specify determines which nodes to include in the search, based on the attributes they contain. The filter uses the standard LDAP format. A basic search filter looks like this:

Where:

<attribute>

is an LDAP attribute. Some commonly used attributes are:

  • ObjectClass (typically, the type of node)
  • mail  (email address)
  • sn  (surname)
  • givenName  (given name)
  • uid  (user ID)

<operator>

defines the relationship between the <attribute> and the <value>. The basic operators for search filters are:

  • = returns entries whose attribute is exactly equal to the value.
  • >= returns entries whose attribute is greater than or equal to the value.
  • <= returns entries whose attribute is less than or equal to the value.
  • > returns entries whose attribute is greater than the value.
  • < returns entries whose attribute is less than the value.
  • ~= returns entries whose attribute value approximately matches the specified value. Typically, this is an algorithm that matches words that sound alike.

<value>

is the value associated with the attribute in the LDAP directory. You can use the asterisk (*) wildcard value to search for any value defined for the attribute.

ClosedExamples

Filter Matches

ObjectClass=*

All nodes in the LDAP directory. (The ObjectClass attribute is usually contained in every node.)

mail=*

All nodes containing an email address entry.

sn=johnson

All nodes with a surname entry of "Johnson".

sn=jo*

All nodes with a surname entry that starts with the two characters "jo", for example, "Johnson", "Jones", and "Jordan".

If you are using an LDAP server that supports complex expressions, you can use Boolean operators to define a complex search filter:

Where:

<boolean operator>

defines the relationship between the filters. The Boolean operators for complex search filters are:

  • & also written as AND - returns entries matching all the specified filters.
  • | also written as OR - returns entries matching one or more of the specified filters.
  • ! also written as NOT - returns entries for which the filter is not true. You can apply this Boolean operator only to a single filter.

<filter>

is a basic search filter in <attribute><operator><value> format.

ClosedExamples

Filter Matches

(&(mail=Sales@your-companyname-here.com)(sn=Johnson))

all nodes with both your Sales email address and a surname of "Johnson".

(|(sn=Jensen)(sn=Johnson))

all nodes containing the last name "Jensen" or the last name "Johnson".

(!(mail=vince@your-companyname-here.com))

all nodes except those containing Vince's email address.
  Contact your LDAP server administrator for details of the attributes supported and values defined for your organization.

Attributes to Retrieve

For the nodes identified by the Target DN, Scope and Filter, you must specify the attributes whose values you want retrieved. The values of the attributes you specify must be user names or email addresses, as these are the only values Clearswift Gateway can accept. If you specify two or more attributes, separate them with commas.

Requesting Paging

Each LDAP server has a maximum number of nodes it will include in a single query. If the number of nodes in your search exceeds that limit, the server will return only its maximum number of results. You can avoid this limit by using the option to allow paging requests, and by specifying a paging size no greater than the maximum number of nodes the LDAP server includes in a query. Then, if the number of nodes in your search exceeds the paging size, Clearswift Gateway automatically splits your search into multiple queries, each bounded by the paging size. The effect is that the LDAP server searches all the required nodes.

Group Expansion

If the LDAP server is configured to allow recursion down a hierarchy of groups you can use the Group Expansion option. If you select Group Expansion you can select: