Using cfldap

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

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; name

n

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