The cfldap tag lets you search an LDAP directory. The tag returns a ColdFusion query object with the results, which you can use as you would any query result. When you query an LDAP directory, you specify the directory entry where the search starts and the attributes whose values to return. You can specify the search scope and attribute content filtering rules and use other attributes to further control the search.
The search scope sets the limits of a search. The default scope is the level below the distinguished name specified in the start attribute. This scope does not include the entry identified by the start attribute. For example, if the start attribute is "ou=support, o=adobe" the level below support is searched. You can restrict a query to the level of the start entry, or extend it to the entire subtree below the start entry.
The search filter syntax has the form attribute operator value. The default filter, objectclass=*, returns all entries in the scope.
The following table lists the filter operators:
Operator |
Example |
Matches |
---|---|---|
=* |
(mail=*) |
All entries that contain a mail attribute. |
= |
(o=adobe) |
Entries in which the organization name is adobe. |
~= |
(sn~=Hansen) |
Entries with a surname that approximates Hansen. The matching rules for approximate matches vary among directory vendors, but anything that "sounds like" the search string should be matched. In this example, the directory server might return entries with the surnames Hansen and Hanson. |
>= |
(st>=ma) |
The name "ma" and names appearing after "ma" in an alphabetical state attribute list. |
<= |
(st<=ma) |
The name "ma" and names appearing before "ma" in an alphabetical state attribute list. |
* |
(o=macro*) |
Organization names that start with "macro". |
|
(o=*media) |
Organization names that end with "media". |
|
(o=mac*ia) |
Organization names that start with "mac" and end with "ia". You can use more than one * operator in a string; for example, m*ro*dia. |
|
(o=*med*) |
Organization names that contain the string "med", including the exact string match "med". |
& |
(&(o=adobe) (co=usa)) |
Entries in which the organization name is "adobe" and the country is "usa". |
| |
(|(o=adobe) (sn=adobe) (cn=adobe)) |
Entries in which the organization name is "adobe" or the surname is "adobe", or the common name is "adobe". |
! |
(!(STREET=*)) |
Entries that do not contain a StreetAddress attribute. |
The Boolean operators & and | can operate on more than two attributes and precede all of the attributes on which they operate. You surround a filter with parentheses and use parentheses to group conditions.
If the pattern that you are matching contains an asterisk, left parenthesis, right parenthesis, backslash, or NUL character, you must use the following three-character escape sequence in place of the character:
Character |
Escape sequence |
---|---|
* |
\2A |
( |
\28 |
) |
\29 |
\ |
\5C |
NUL |
\00 |
For example, to match the common name St*r Industries, use the filter:
(cn=St\2Ar Industries).
LDAP v3 supports an extensible match filter that permits server-specific matching rules. For more information on using extensible match filters, see your LDAP server documentation.
Typically, you do not use a query that gets all the attributes in an entry. Such a query would return attributes that are used only by the directory server. However, you can get all the attributes by specifying attributes="*" in your query.
If you do this, ColdFusion returns the results in a structure in which each element contains a single attribute name-value pair. The tag does not return a query object. ColdFusion does this because LDAP directory entries, unlike the rows in a relational table, vary depending on their object class.
For example, the following code retrieves the contents of the Airius directory:
<cfldap name="GetList" server=#myServer# action="query" attributes="*" scope="subtree" start="o=airius.com" sort="sn,cn">
This tag returns entries for all the people in the organization and entries for all the groups. The group entries have a different object class, and therefore different attributes from the person entries. If ColdFusion returned both types of entries in one query object, some rows would have only the group-specific attribute values and the other rows would have only person-specific attribute values. Instead, ColdFusion returns a structure in which each attribute is an entry.