Unmasking the LDAP Search Filter
The time has come you need to locate critical information that resides in your corporate LDAP directory. Until now, you have avoided learning the LDAP search functions. The reasons why can vary. Perhaps your eyes glazed over looking at the seemingly overwhelming information in RFCs 2251, 2254, and 2255, or maybe you heard from others that there was a steep learning curve. You might have tried the ldapsearch command from the DOS or UNIX command line without success.
Fear not, our guide below will aid your mastery of this invaluable tool. Once you have learned a few commands, you can easily locate the information contained within your existing corporate contact repository for yourself.
In the first article in this series on the powerful capabilities of LDAP search functions, we introduced you to some of the basic concepts and some potential uses for them. In the second article, we will explore the core of the LDAP search function the search filter syntax itself.
LDAP Search FrameworkLDAP search filters need to be understood within a framework. The framework includes what attributes you are searching on and the value or range of values that you are trying to match. Each search filter involves at a minimum of three components:
- The attribute(s) to search for, called the attribute data type
- The search filter operator that will determine what to match sometimes called the match operator
- The actual value of the attribute you are searching for
Each search needs to have a minimum of one of each of the components. You can create compound search filters by connecting two or more search filters modules. They are enclosed in parentheses to clarify filter content and will include one or more of three compound search filter operators (AND, OR, NOT). You can add as many compound and wildcard filters as needed as long as you have the correct number of matching parentheses.
Attribute Data Type
Attribute data types are typically the object class or attribute name. Each attribute type has a unique OID (ObjectIdentifiers), which are written as dot delimited numbers (18.104.22.168). Each OID is registered and follows a hierarchical structure.
Exact Match (Equality Filter or =) - Return records exactly matching the attribute value.
Wild Card (Presence Filter) - Useful to determine if an attribute exists or if you wish to find all values for an attribute. For example, email=* will return all records with e-mail addresses.
Wild Card (Substring Filter or *) - Returns records that match the attribute value combined with one or more wildcards. Use wildcards if you are not sure of an exact value. Wildcards are usually placed at the start or end of an attribute value. They can also be placed both in front and back of a string. Eg. *smi* will match all strings that contain the substring "smi". One caveat, use wildcards with restraint they may return too many records or take too long to run. A badly formed wild card will surely bring the wrath of your LDAP administrator upon your head.
Approximate Search Filters
Greater Than/Greater Equal (>,>=) - Returns records that are greater than or greater than equal to the attribute value. For example, (sn>foutley) will return values that sort higher than the string "foutley." The sort order is determined by the matching rule associated with the attribute.
Less Than/Equal (<,<=)- Returns records that are less than or less than equal to the attribute value.
Approximately Equal(~=)- Returns records that are close to the attribute value. For example, (givenname~=curt) may return those with first names of kurt or curtis. This can be a useful search if you do not know the exact spelling of a name.
Compound filters are just like the familiar Boolean operators in any other programming language or search function. Important note: The compound filter is placed before the search filter and it is enclosed in its own set of parentheses.
NOT(!) - Returns records that do not match any search filter criteria. This filter may be used either alone or with other compound filters. For example (!(uid=kurt)) will return those records that have a user id not equal to kurt. Note this includes those records where uid is not present.
AND (&)- Returns records that match all multiple search filter conditions. For example, (&(l=USA)(sn=smithers)) returns those records with a locality of USA and a last name of smithers.
OR (|)- Returns records that match at least one of the multiple search filter conditions. For example, (|(l=UK) (l=USA)) returns those records in either the USA or UK locality (country in this case). Note that this could easily be a long search returning many records.
Examples LDAP Search Functions
To help you get the hang of the system, we have included some examples to ponder.
(&(l=USA)(!(sn=patel))) - Shows all records in the USA locality that do not have a last name of patel.
(!(&(drink=beer)(description=pagan))) - Shows all records where drink is not equal to beer and description is not equal to pagan. Removing the not operator WILL return a record at a popular open LDAP directory site.
(!(uid=*)) - Returns all records without a UID.
LDAP attributes values may include special characters. These include \ (backslash), * (asterisk), and several others depending on the LDAP flavor. To include these characters in your search you must preface the desired character with the escape sequence. For example, (sn=hodges\5cSmith) will search on the string hodge\smith. For more detailed information on how to incorporate special characters in a search, review the Microsoft search filter reference listed below.
LDAP version 3 provides you the capability of building your match operators and rules for a particular attribute or object. Once these are created, they can be referred to in your search string. (sn:22.214.171.124.444:=foutley) for example compares entries with a surname of foutley using the matching rule designated by (in this case fictional) OID 126.96.36.199.444. These matching rules typically relate to syntax and text case of matching entries. There is an LDAP draft draft-ietf-ldapbis-syntaxes specifically for syntaxes and matching rules. An optional (:dn) argument can be used to search the distinguished name attribute as well. (sn:dn:188.8.131.52.444:=foutley)searches surname and distinguished name for records containing foutley.
In addition to the operators and syntax rules listed above, there are also a large number of error messages and result codes to help you refine and debug your searches. For a complete list of the error messages and their meanings, see the Netscape reference below. Here are just a few of the most useful ones:
- A result code of 0 means a successful operation.
- A result code of 18 means that you used a matching rule that does not exist for a particular attribute.
- A result code of 50 means you do not have the rights to perform an operation.
Next Time on LDAP Searches
So far, in these two articles, we have presented a high-level overview of LDAP searches. As you can see, LDAP searches are not all that complicated. You do not need to be a full-time coding geek to employ this useful tool. Next time, in part 3, we'll discuss how to use LDAP searches in URLs, e-mail and in the command line. We will conclude the series with an introduction to LDAP browsers. Until next time, happy searching!
www.hawaii.edu/brownbags/ldap/ldap2.pdf Good presentation on LDAP and LDAP search.
http://www.hawaii.edu/ldap/details.html Good overview of LDAP URL syntax with examples.
http://java.sun.com/products/jndi/tutorial/basics/directory/filter.html Sun overview on search filters.
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/adsi/adsi/search_filter_syntax.asp Overview of search filters including special characters.
http://developer.netscape.com/docs/manuals/dirsdk/csdk30/error.htm Netscape list of LDAP v3 compliant and custom error codes.
LDAP Public Directories
http://www.emailman.com/ldap/public.html List of public directories that you can use for testing queries.
http://www.alvestrand.no//objectid/ Great overview on registering OIDs and listing those already defined.
http://perl-ldap.sourceforge.net/rfc.html One location (of many) to find LDAP
http://www.ietf.org/ids.by.wg/ldapbis One of the IETF standard groups that are revising the LDAP v3 protocol. Also has an active mailing list you can join.