{scrollbar}

This section gives an overview on how to search your directory

22list

Searching with LDAP

From a users point of view, searching is the most important LDAP operation at all. Normally end users perform queries against a directory with the help of custom applications, which fit their specific needs. E-Mail programs like Thunderbird for instance allow the look up of adresses in a convenient way:

The actual LDAP search operation with all it's parameters is hidden here (which is desired in this situation).

So, when do you need the original LDAP syntax and parameters? Here are some use cases:

  • command line tools (ldapsearch)
  • LDAP clients (browsers, administrative tools)
  • custom application development (using an API like JNDI)
  • configuration of software products, which integrate LDAP directories

The following description about LDAP searches matches all of the above.

Important parameters in LDAP searches

The search base and the search scope are used to reduce the amount of entries, which should take into account as result entries. To the set of entries defined by base and scope, a filter is applied.

Search base

The search base determines an entry as the starting point within the tree. No entries above this point will be returned within the search result.

Search scope

The search scope defines the set of entries below the base, which is examined by the server.

Scope

Description

Base

Only the base entry

One-Level

One level below, all direct children of the base entry

Subtree

The whole subtree below the base, including the base entry

Base scope is useful for reading attribute values of a particular entry. One example for using One_Level scope is expanding the tree in graphical LDAP clients. For extensive investigations within your data, Subtree is the most powerful option.

Search Filters

If you look for entries with certain properties (attribute values), you need search filters to delimit the result set in order to contain the entries which meet your search criteria.

Within a filter expression, the following operators are used to combine an attribute name with a value

Name

Operator

Example

Example macthes

Presence

=*

(mail=*)

all entries which have at least one mail attribute value

Equality

=

(givenName=William)

all antries where a givenName attribute value equals "William"

Substring

=

(sn=H*)

all entries where a sn (surname) attribute value starts with "H"

Order

<=, >=

(ou>=N)

all entries where a ou attribute value is greater than "N"

Approximatly

~=

(sn~=Mayer)

all entries where an sn attribute value is similar to "Mayer"

Simple filter expressions like the examples above can be combined with the help of boolean operators. To form expressions with them, the prefix notation is used. Prefix means that the operator does not stand between the operands (like in "(3 + 6)"), but before them (like in "(+ 3 6)"), which allows you to use more than two operands within a single expression (like in "(+ 3 6 2)").

Name

Operator

Example

Example matches

and

&

(&(objectClass=person)(sn=H*))

all person entries with surnames starting with "H"

or

|

(&(objectClass=person)(|(sn=H*)(sn=W*)))

all person entries with surnames starting with "H" or "W"

not

!

(&(objectClass=person)(!(mail=*))

all person entries without mail address

(objectClass=*)

Quite often, for instance as default in UI tools, you will see the search filter (objectClass=*). It is used if a filter expression is required as a parameter, but all entries should be returned regardless of their attribute values. (objectClass=*) does the job, because each entry has at least one objectClass value occurence (normally two or more), the filter therefore matches all entries.

Searching with a command line tool

If you connect to ApacheDS with command line tools, you execute searches against the directory with the ldapsearch command.

An example

The query searches all entries below "ou=people,o=sevenSeas" which match the filter (&(objectClass=person)(givenName=William)), and therefore are persons called William.

$ ldapsearch -h zanzibar -p 10389 -D "uid=admin,ou=system" -w secret \\ -b "ou=people,o=sevenSeas" -s sub "(&(objectClass=person)(givenName=William))" uid mail dn: cn=William Bush,ou=people,o=sevenSeas uid: wbush mail: wbush@royalnavy.mod.uk dn: cn=William Bligh,ou=people,o=sevenSeas uid: wbligh mail: wbligh@royalnavy.mod.uk $

The tool return the attribute values for the attributes given in the command line (uid and mail). If no attributes are provided, all attributes the user is allowed to read will be returned.

Command line options used in the example

Option

Example value

Meaning

-h

zanzibar

Hostname of LDAP server to connect to (default is localhost)

-p

10389

Port on which the server listens (default is 389)

-D

"uid=admin,ou=system"

Distinguished name of bind user

-w

secret

Password of bind user

-b

"ou=people,o=sevenSeas"

search base

-s

sub

search scope, one of "base", "one", or "sub" (default is sub)

Searching with a Java program

Here is the same search as above, performed against the "Seven seas" example from within a Java program with the help of JNDI.

java package search; import java.util.Hashtable; import javax.naming.Context; import javax.naming.NamingEnumeration; import javax.naming.NamingException; import javax.naming.directory.Attribute; import javax.naming.directory.Attributes; import javax.naming.directory.DirContext; import javax.naming.directory.InitialDirContext; import javax.naming.directory.SearchControls; import javax.naming.directory.SearchResult; public class SimpleSearch { public static void main(String[] args) throws NamingException { // JNDI connection data, move them to jndi.properties Hashtable env = new Hashtable(); env.put(Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.ldap.LdapCtxFactory"); env.put(Context.PROVIDER_URL, "ldap://zanzibar:10389/"); env.put(Context.SECURITY_AUTHENTICATION, "simple"); env.put(Context.SECURITY_PRINCIPAL, "uid=admin,ou=system"); env.put(Context.SECURITY_CREDENTIALS, "secret"); try { DirContext ctx = new InitialDirContext(env); String base = "ou=people,o=sevenSeas"; String filter = "(&(objectClass=person)(givenName=William))"; SearchControls ctls = new SearchControls(); ctls.setSearchScope(SearchControls.SUBTREE_SCOPE); ctls.setReturningAttributes(new String[] { "uid", "mail" }); NamingEnumeration resultEnum = ctx.search(base, filter, ctls); while (resultEnum.hasMore()) { SearchResult result = (SearchResult) resultEnum.next(); // print DN of entry System.out.println(result.getNameInNamespace()); // print attributes returned by search Attributes attrs = result.getAttributes(); NamingEnumeration e = attrs.getAll(); while (e.hasMore()) { Attribute attr = (Attribute) e.next(); System.out.println(attr); } System.out.println(); } ctx.close(); } catch (NamingException e) { System.out.println(e.getMessage()); } } }

The output of the program looks like this:

cn=William Bush,ou=people,o=sevenSeas mail: wbush@royalnavy.mod.uk uid: wbush cn=William Bligh,ou=people,o=sevenSeas mail: wbligh@royalnavy.mod.uk uid: wbligh

Key for LDAP searches with JNDI are the search methods in the javax.naming.directory.DirContext interface (javadoc). Learn more about JNDI and how to perform searches against an LDAP directory with it in the JNDI tutorial

Searching with a graphical client tool

If you connect to ApacheDS with graphical tools, normally a search dialog is provided which allows you to enter the parameters needed to perform your search.

Here is the search query used throughout this section, performed with Softerra LDAP Browser:

If you prefer to use JXplorer, the search dialog looks like this:

Resources

  • RFC 4515 LDAP: String Representation of Search Filters
  • manpage of ldapsearch contains the options for the OpenLDAP of this LDAP search tool
  • The JNDI tutorial is a good resource to learn about LDAP client programming with Java
  • No labels