# CFLDAP

CFLDAP provides an interface to LDAP (Lightweight Directory Access Protocol) directory servers like the Netscape Directory Server. For complete examples of CFLDAP usage, refer to Developing Web Applications with ColdFusion.

### Syntax

    <CFLDAP SERVER="server_name"
        PORT="port_number"
        USERNAME="name"
        PASSWORD="password"
        ACTION="action"
        NAME="name"
        TIMEOUT="seconds"
        MAXROWS="number"
        START="distinguished_name"
        SCOPE="scope"
        ATTRIBUTES="attribute, attribute"
        FILTER="filter"
        FILTERFILE="<file_name>,<stanza_name>"
        SORT="attribute[, attribute]..."
        SORTCONTROL="nocase" and/or "desc" or "asc"
        DN="distinguished_name"
        STARTROW="row_number"
        MODIFYTYPE="REPLACE" or "ADD" or "DELETE"
        REBIND="Yes/No"
        REFERRAL="number_of_allowed_hops"
        SECURE="multi_field_security_string"
        SEPARATOR="separator_character"
        >

#### SERVER

Required. Host name ("biff.upperlip.com") or IP address ("192.1.2.225") of the LDAP server.

#### PORT

Optional. Port defaults to the standard LDAP port, 389.

#### USERNAME

Optional. If no user name is specified, the LDAP connection will be anonymous.

#### PASSWORD

Optional. Password corresponds to user name.

#### ACTION

Optional. Specifies the LDAP action. There are five possible values:

- Query -- (Default) Returns LDAP entry information only. Requires NAME, START, ATTRIBUTES attributes. See Usage for more information.
- Add -- Adds LDAP entries to the LDAP server. Requires ATTRIBUTES.
- Modify -- Modifies LDAP entries on an LDAP server with the exception of the distinguished name ("DN") attribute. Requires DN, ATTRIBUTES. See the MODIFYTYPE attribute for additional controls.
- ModifyDN -- Modifies the distinguished name attribute for LDAP entries on an LDAP server. Requires DN, ATTRIBUTES.
- Delete -- Deletes LDAP entries on an LDAP server. Requires DN.

#### NAME

Required for ACTION="Query". The name you assign to the LDAP query.

#### TIMEOUT

Optional. Specifies the maximum amount of time in seconds to wait for LDAP processing. Defaults to 60 seconds.

#### MAXROWS

Optional. Specifies the maximum number of entries for LDAP queries.

#### START

Required for ACTION="Query". Specifies the distinguished name of the entry to be used to start the search.

#### SCOPE

Optional. Specifies the scope of the search from the entry specified in the Start attribute for ACTION="Query". There are three possible values:

- OneLevel -- (Default) Searches all entries one level beneath the entry specified in the START attribute.
- Base -- Searches only the entry specified in the START attribute.
- Subtree -- Searches the entry specified in the START attribute as well all entries at all levels beneath it.

#### ATTRIBUTES

Required for ACTION="Query", Add, ModifyDN, and Modify. For queries, specifies the comma-separated list of attributes to be returned for queries. For queries, you can also specify the wild card "*" to get all the attributes associated with the entry. In addition, it can be used to specify the list of update columns for ACTION="Add" or "Modify". When used with ACTION="Add" and Action="Modify", separate multiple attributes with a semicolon. When used with ACTION="ModifyDN", ColdFusion passes attributes to the LDAP server without performing any syntax checking.

#### FILTER

Optional. Specifies the search criteria for ACTION="Query". Attributes are referenced in the form: "(attribute operator value)". Example: "(sn=Smith)". Default is "objectclass=*".

If you also specify the FILTERFILE attribute, the filter is considered to be a search string not a filter.

#### FILTERFILE

Optional. Specifies the name of a filter file and the name of the stanza tag within that file that contains the LDAP filter string specification. You can specify either an absolute path name or a simple file name to identify the file. If you use a simple file name, CFLDAP looks for it in ColdFusion's default LDAP directory. The default LDAP directory is C:\cfusion\ldap. The filter file must be in LDAP filter file format as defined in RCF-1558.

#### SORT

Optional. Indicates the attribute or attributes to sort query results by. Use a comma to separate attributes if more than one attribute is specified.

#### SORTCONTROL

Optional. Specifies how to sort query results. Enter "nocase" for a case-insensitive sort. By default, sorts are case-sensitive. You can also enter "asc" for an ascending sort and "desc" for a descending sort. You can enter a combination of these, for example, "nocase" and "asc". The default sort order is ascending.

#### DN

Required for ACTION="Add", Modify, ModifyDN, and Delete. Specifies the distinguished name for update actions. Example: "cn=Barbara Jensen, o=Ace Industry, c=US".

#### STARTROW

Optional. Used in conjunction with ACTION="Query". Specifies the first row of the LDAP query that is to be inserted into the ColdFusion query. The default is 1. See the Usage section for more information about the query object and query variables.

#### MODIFYTYPE

Optional. Indicates whether to Add, Delete, or Replace an attribute within a multi-value list of attributes, as follows:

- Add - appends the new attribute to any existing attributes.
- Delete - deletes the specified attribute from the set of existing attributes.
- Replace (default) - Replaces an existing attribute with the specified attribute or attributes.

Note that you cannot add attributes that already exist or that are NULL.

#### REBIND

Optional. Yes or No. If you set REBIND to Yes, CFLDAP attempts to rebind the referral callback and reissue the query via the referred address using the original credentials. The default is No, which means referred connections are anonymous.

#### REFERRAL

Optional. Specifies the number of hops allowed in a referral. Valid values for this are integers equal to or greater than zero. If you specify zero, you turn off CFLDAP's ability to use referred addresses; thus, no data is returned.

#### SECURE

Optional. Identifies the type of security to employ, CFSSL_BASIC or CFSSL_CLIENT_AUTH, and additional information that is required by the specified security type.

    SECURE="CFSSL_BASIC,certificate_db"

or

    SECURE="CFSSL_CLIENT_AUTH,certificate_db,certificate_name,
                    key_db,key_password"

These fields have the following values:

certificate_db: The name of the certificate database file (in Netscape cert7.db format). You can specify either an absolute path or a simple file name.

certificate_name: The name of the client certificate to send the server.

key_db: Keyword database that holds the public/private key-pair (in Netscape key3.db format). You can specify either an absolute path or a simple file name.

keyword_db: The password to key database.

If you use a simple file name for certificate_db or keyword_db, CFLDAP looks for it in ColdFusion's default LDAP directory. The default LDAP directory is C:\cfusion\ldap.

Refer to the Usage section for information about the differences between the two types of security: CFSSL_BASIC and CFSSL_CLIENT_AUTH types.

#### SEPARATOR

Optional. Specifies the character that CFLDAP uses to separate attribute values in multi-value attributes. This character is used by the QUERY, ADD, and MODIFY action attributes, and is used by CFLDAP to output multi-value attributes. The default character is the comma (,).

### Usage

If you use the Query ACTION, CFLDAP creates a query object, allowing you access to information in the three query variables as described in the following table.

CFLDAP Query Variables
Variable Names | Description
--- | ---
    queryname.RecordCount
| The total number of records returned by the query.
    queryname.CurrentRow
| The current row of the query being processed by CFOUTPUT.
    queryname.ColumnList
| The list of the column names in the query.

The CFSSL_BASIC type of security provides V2 SSL, and the CFSSL_CLIENT_AUTH type of security provides V3 SSL. V2 SSL provides encryption and server authentication. V3 SSL adds to this certificate-based client authentication.

Both forms of security encrypt the conversation, and the server always sends a digital certificate to confirm that it is the right server.

For CFSSL_BASIC, you must also specify the CFLDAP attributes USERNAME and PASSWORD to authenticate yourself. V2 then encrypts the password prior to transmission.

For CFSSL_CLIENT_AUTH, you do not send a user name and password; instead, you perform authentication by a digital certificate that you send to the server. CFSSL_CLIENT_AUTH is much more secure; however, it is difficult to administer since all the clients must have certificates, which the server must be able to validate, and all the certificates must have keys associated with them and passwords to protect those keys.

### Example

    <!---  This example shows the use of CFLDAP --->
    <HTML>
    <HEAD>
    <TITLE>CFLDAP Example</TITLE>
    </HEAD>

    <BODY bgcolor=silver>
    <H3>CFLDAP Example</H3>

    <P>CFLDAP provides an interface to LDAP (Lightweight Directory Access
    Protocol) directory servers like BigFoot
    (<a href="http://www.bigfoot.com">http://www.bigfoot.com</A>).
    <P>Enter a name (try your own name) and search a public LDAP resource.
    ...
    <!--- If the server has been defined, run the query --->
    <CFIF IsDefined("form.server")>
    <!--- check to see that there is a name listed --->
    <CFIF form.name is not "">
    <!--- make the LDAP query --->
    <CFLDAP
     SERVER="ldap.bigfoot.com"
     ACTION="QUERY"
     NAME="results"
     START="cn=#name#,c=US"
     FILTER="(cn=#name#)"
     ATTRIBUTES="cn,o,l,st,c,mail,telephonenumber"
     SORT="cn ASC">
    <!--- Display results --->
        <CENTER>
        <TABLE BORDER=0 CELLSPACING=2 CELLPADDING=2>
         <TR>
              <TH COLSPAN=5><CFOUTPUT>#results.RecordCount# matches found
                </CFOUTPUT></TH>
         </TR>
         <TR>
              <TH><FONT SIZE="-2">Name</FONT></TH>
              <TH><FONT SIZE="-2">Organization</FONT></TH>
              <TH><FONT SIZE="-2">Location</FONT></TH>
              <TH><FONT SIZE="-2">E-Mail</FONT></TH>
              <TH><FONT SIZE="-2">Phone</FONT></TH>
         </TR>
        <CFOUTPUT QUERY="results">
         <TR>
           <TD><FONT SIZE="-2">#cn#</FONT></TD>
           <TD><FONT SIZE="-2">#o#</FONT></TD>
           <TD><FONT SIZE="-2">#l#, #st#, #c#</FONT></TD>
           <TD><FONT SIZE="-2"><A HREF="mailto:#mail#">#mail#</A></FONT></TD>
           <TD><FONT SIZE="-2">#telephonenumber#</FONT></TD>
         </TR>
        </CFOUTPUT>
        </TABLE>
        </CENTER>
    </CFIF>
    </CFIF>
    </BODY>
    </HTML>