The capability to query LDAP servers is useful for ColdFusion developers. Many organizations use LDAP in one fashion or another as a companywide data repository. Exchange Server and ADSI (Microsoft's Active Directory Service Interface) are two examples that provide developers an LDAP channel to this data.
ColdFusion's <cfldap> tag is the mechanism you'll use to interface this directory data. Although there are other ways to retrieve this data, such as using <cfobject> and COM, <cfldap> provides a less complicated interface to the same data.
Chapter 26, "Extending ColdFusion with COM," for coverage of COM integration via <cfobject>.
Although it is ultimately up to you, the developer, to decide how you'll use <cfldap>, the following are some common uses:
Creating interfaces for querying public LDAP servers, as for a local university.
Creating interfaces for querying, updating, and deleting company directory entries for employees, departments, and the like. A company "phonebook" is one example of this.
Creating interfaces to other data stored within an LDAP server. Company information is one of the many uses for LDAP.
Depending on the server you're accessing, you may need special privileges to perform certain actions, such as adding or deleting LDAP entries. Most public LDAP servers give anonymous access that allows you only to query the server.
For corporate uses, LDAP usually requires authentication with a username and password combination. Together, these restrict access to data that corresponds to the security level of the individual performing the operations. With LDAPv3, you can also use security certificates for authentication, as explained later in the section on the SECURE attribute.
The <cfldap> tag, like most ColdFusion tags, takes several attributes. Some attributes are required depending on the context of the tag, but in all cases there are several optional values you may set as well.
NOTE
The <cfldap> tag does not require a closing tag.
Table 22.2 shows the available attributes of the <cfldap> tag with corresponding descriptions for each. Some of these attributes require detailed descriptions, which follow the table.
NAME | DESCRIPTION |
|---|---|
ACTION | Optional. One of five possible actions for <cfldap> to perform. Values are QUERY, ADD, MODIFY, MODIFYDN, or DELETE. If none is specified, the default is QUERY. |
NAME | Required if ACTION="Query". This represents the name of the query object returned from the <cfldap> query. |
SERVER | Required. The address hosting the LDAP server. Entries may be in the form of the server's IP address (that is, 127.0.0.1) or its DNS entry (that is, ldap.server.com). |
PORT | Optional. The port to which LDAP is configured for listening. The default is 389. |
USERNAME | Required if secure attribute is set to cfssl_basic. |
PASSWORD | Optional. The password used in conjunction with the USERNAME attribute for authentication. |
TIMEOUT | Optional. the time, in seconds, allowed for the LDAP operation before timeout occurs. If none is provided, the default is 60 seconds. |
Optional. Used only with ACTION="Query", this specifies the number of records to return from the LDAP query, similar to the <cfquery> tag. Note that this attribute does not work with all LDAP servers. | |
START | Required (and only used) if ACTION="Query". This represents the DN starting point from which to begin the search within the DIT. |
SCOPE | Optional. Defines the scope for searching the Directory Information Tree (DIT), starting at the value specified in the START attribute. Possible values are Base, OneLevel, or SubTree. |
ATTRIBUTES | Required for QUERY, ADD, MODIFY, and MODIFYDN actions. When used with QUERY, it represents a comma-delimited list of return values used as columns in a query output; an asterisk (*) returns all values. For ADD and MODIFY, it represents a semicolon-separated list of add/modify values. For MODIFYDN, it represents the new DN for the entry and does not check for correct syntax. |
FILTER | Optional. Used with ACTION="Query" to provide the search criteria for the query. The default filter is objectClass=*, which returns all values. |
SORT | Optional. A comma-delimited list of attributes and sort directions by which to sort a query, as in SORT="cn ASC, mail DESC". |
SORTCONTROL | Optional. A comma-delimited list of sort control options for a query. Possible values are asc, desc, and nocase. Sorting, by default, is case-sensitive in ascending order (asc). The desc value sorts the query in descending order, and nocase discards case-sensitivity. Values can be used in tandem, as in SORTCONTROL= "nocase, desc". |
DN | Required for DELETE, ADD, MODIFY, and MODIFYDN actions. Represents the Distinguished Name for the entry being operated on. |
STARTROW | Optional. Used only with ACTION="Query", this specifies the starting row for returning records. The default is 1. |
MODIFYTYPE | Optional. Used only with ACTION="Modify", this specifies the way to handle modifications within the attribute list. Possible values are add, replace, and delete. Default value is "Replace". |
REBIND | Optional. Boolean value indicating whether <cfldap> should rebind the referral callback and reissue the query via the referred address using the original credentials. Default value is "no". |
REFERRAL | Optional. Specifies the number of hops allowed in a referral A zero value indicates, <cfldap>'s capability to use referred addresses is disabled, and no data is returned. |
SECURE | Optional. Identifies the type of security to use, such as CFSSL_BASIC or CFSSL_CLIENT_AUTH, and additional information that is required by the corresponding security type. Possible field values are certificate_db, certificate_name, key_db, and keyword_db. |
SEPARATOR | Optional. The character used to separate values in multivalue attributes. The default is a comma (,). |
DELIMITER | Optional. The character used to separate name=value pairs. The default is a semicolon (;). |
To use the <cfldap> tag in your applications, use the following format:
<CFLDAP ACTION="Query OR Add OR Modify OR ModifyDN OR Delete" NAME="returned query name" SERVER="server name OR server IP address" PORT="ldap port number" USERNAME="cn=username" PASSWORD="password" TIMEOUT="timeout in seconds" MAXROWS="maximum records to be returned from a query" START="distinguished name to start searching from" SCOPE="Base OR OneLevel OR SubTree" ATTRIBUTES="attributes to return OR Add OR delete OR modify" FILTER="search filter(s)" SORT="attribute ASC OR DESC" SORTCONTROL="nocase AND/OR desc OR asc" DN="distinguished name" STARTROW="row number to start query results" MODIFYTYPE="Replace OR Add OR Delete" REBIND="Yes OR No" REFERRAL="maximum number of hops for referral addressing" SECURE="multiple field security string" SEPARATOR="character separator for multi-attribute values" DELIMITER="character delimiter for name=value pairs">
Because some of <cfldap>'s attributes are a bit involved, the next few sections discuss in more depth how these attributes work.
ColdFusion's <cfldap> tag supports five distinct actions:
QUERY
ADD
MODIFY
MODIFYDN
DELETE
QUERY is the default. The QUERY action allows you to return a query object (recordset) from an LDAP server. This can be used in the same way as a normal query, such as one returned from the <cfquery> tag. Three variables, in addition to the query results, are available to the returned query object:
RecordCount. The number of records returned from the query object.
ColumnList. A comma-delimited list of column names in the query.
CurrentRow. The current row index of the query being processed by an output mechanism, such as <cfoutput> or <cfloop>.
When ACTION is set to QUERY, you are also required to use the NAME, ATTRIBUTES, and START parameters. So at its simplest, your call to <cfldap> would look like:
<CFLDAP ACTION="QUERY" NAME="name of query" SERVER="server location" ATTRIBUTES="attribute list" START="starting location for the query">
NOTE
Unlike <cfquery>, the <cfldap> tag does not return the ExecutionTime variable when the ACTION is set to QUERY.
The ADD action is used to add entries to your LDAP server. This action requires the DN and ATTRIBUTES parameters. In this context, the DN is used to specify where to place the added entry in the DIT and should contain the full DN sequence. The ATTRIBUTES parameter is used to specify the name=value pairs to be added at the location specified in the DN parameter. Each name=value pair should be delimited with a semicolon (;), unless otherwise specified in the DELIMITER parameter.
The most basic form of an ADD action is as follows:
<CFLDAP ACTION="ADD" SERVER="server location" ATTRIBUTES="name=value; name2=value2; namen=valuen" DN="the distinguished name to add">
The MODIFY action allows you to modify attribute values for LDAP entries, one or more at a time. The only attribute that cannot be modified through this action is the DN, which is modified through the MODIFYDN action.
As with the ADD action, the MODIFY action's attributes are sent to the ATTRIBUTES parameter in semicolon-separated name=value pairs.
The following is the MODIFY action's basic required format:
<CFLDAP ACTION="MODIFY" SERVER="server location" ATTRIBUTES="name=value; name2=value2; namen =valuen" DN="the distinguished name of the entry to be modified">
The MODIFYDN attribute performs one specific function: It changes the Distinguished Name for an entry. To change the Distinguished Name, you must supply the original DN as well as the new DN replacement:
<CFLDAP ACTION="MODIFYDN" SERVER="server location" ATTRIBUTES="the new replacement DN value" DN="the original DN value being modified">
NOTE
Before you modify a DN entry, make absolutely sure that the syntax is correct. The MODIFYDN attribute of <cfldap> does not check the DN for syntax errors, and as a result, your entry may become malformed.
The only requirement for deleting an entry is the entry's Distinguished Name. Having this value allows <cfldap> to locate the entity you want to delete. After you delete an entry, it is gone, and because of this, you should make sure that the DN value is correct.
To delete an entry, use the following syntax:
<CFLDAP ACTION="DELETE" SERVER="server location" DN="the DN representing the entry to delete">
When querying an LDAP server, <cfldap> provides a means to narrow that searchin addition to filteringwith three types of "branch" scopes. Each of these scopes dictates how the search is performed relative to the value entered in the START attribute. In other words, the START attribute is used as a starting point for the search, and the SCOPE value tells <cfldap> where to search from that starting point. These scopes are as follows:
BASE . If BASE is chosen, <cfldap> only searches the current branch specified in the START attribute. Any branches above or below this branch are not searched.
ONELEVEL . To search a single level below the branch specified in the START attribute, use the ONELEVEL value. This only searches one level below the starting branch. Any branches above or more than one level below this branch are not searched.
SUBTREE . This is the most commonly used value because it searches the entry specified in the START attribute as well as all branches beneath it. SUBTREE will not, however, search branches above the starting value. If you need to search branches higher up in the directory tree, simplify your starting value by making it more generalized.
Because of the recursive nature of the SUBTREE scope, performance may suffer with larger directory structures. As a result, you may want to use a drill-down approach when traversing a large directory, using the ONELEVEL scope in succession.
When modifying an LDAP entry using ACTION="Modify", the MODIFYTYPE attribute allows you to specify which type of modification to perform. Having this capability allows you greater flexibility and control for modifying complex entries.
The following list provides detailed descriptions for each MODIFYTYPE and the action(s) it performs:
ADD . To add an attribute value to a multivalue entry, you can use the ADD modify type. The attribute(s) to be added should be listed in the ATTRIBUTES parameter as a semicolon-separated list, unless a different separator is specified in the SEPARATOR parameter.
DELETE . To delete a specific attribute from a multivalue entry, use the DELETE modify type. The value listed in the ATTRIBUTES parameter represents the value to delete if it exists.
REPLACE . As the default modify type, the REPLACE value overwrites the existing attribute(s) specified in the ATTRIBUTES parameter.
NOTE
Attributes that already exist cannot be added using the MODIFY action. Additionally, entries that contain NULL values cannot be modified.
The SECURE attribute identifies which type of security to use in your LDAP calls. ColdFusion currently supports the CFSSL_BASIC only.
The format for CFSSL_BASIC authentication requires two values:
secure = "CFSSL_BASIC,certificate_db"
When using SECURE, keep the following in mind:
The certificate_db value is the name or path to a valid (Netscape cert7.db format) certificate database file. This value is the default and need not be explicitly specified.
The certificate_name represents the client certificate to send to the server.
The key_db value is the name or path to a valid (Netscape key3.db format) file that contains the public or private key pair for the certificate.
The keyword_db holds the password to the key database (key_db).
If no path information is given for the certificate_db or key_db values, ColdFusion looks for them in the default LDAP directory.