Using cfldap

Using <cfldap>

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.

See 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.

Tag Overview

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.

Table 22.2. <cfldap> Tag Attributes and Descriptions

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.
MAXROWS	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.

The ACTION Attribute

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"> 

The SCOPE Attribute

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.

The MODIFYTYPE Attribute

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

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.