cfldap

Description

Provides an interface to LDAP (Lightweight Directory Access Protocol) directory servers like the Netscape Directory Server. For complete examples of cfldap usage, see Developing ColdFusion Applications.

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

  referral = "number_of_allowed_hops"

  secure = "multi_field_security_string"

  separator = "separator_character"

  delimiter = "delimiter_character">

Attributes

Attribute

Description

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 is anonymous.

password
Optional. Password that corresponds to user name.

action
Optional. Specifies the LDAP action. Options :

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, except the distinguished name dn attribute. Requires dn attribute. See the modifyType attribute for additional controls.

modifyDN    Modifies the distinguished name attribute for LDAP entries on an LDAP server. Requires dn attribute.

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". Options:

oneLevel    (default) Searches entries one level below 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 and entries at all levels below 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. 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 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 of the stanza tag within the file that contains the LDAP filter string specification. You can specify an absolute pathname or a simple filename to identify the file. If you use a simple filename, cfldap looks for it in ColdFusion's default LDAP directory. The default LDAP directory for a user-installed 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(s) by which to sort query results. Use a comma to separate attributes.

sortControl
Optional. Specifies how to sort query results. Enter one or more of the following values:

nocase    Case-insensitive sort

asc    (default) Ascending case-sensitive sort

desc    Descending case-sensitive sort

You can enter a combination of sort types; for example, sortControl = "nocase, asc".

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 to insert 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 in a multi-value list of attributes, as follows:

add    Appends the attribute to any existing attributes.

delete    Deletes the attribute from the set of existing attributes.

replace    (default) Replaces an attribute with the specified attribute or attributes.

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 by 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 disable 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 an absolute path or a simple filename.

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 an absolute path or a simple filename.

keyword_db    The password to key database.

If you use a simple filename for certificate_db or keyword_db, cfldap looks for it in the ColdFusion default LDAP directory location for a user-installed LDAP directory (C:\cfusion\ldap for Windows, ).
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 by cfldap to output multi-value attributes. The default character is the comma (,). For example, if you set the value of separator to a dollar sign ($), the attributes attribute could have the following value:
"objectclass = top$person"
where the first value of objectclass is "top", and the second value is "person". Using an alternate character to separate values of an attribute eliminates confusion when the values themselves have commas in them.

delimiter
Optional. Specifies the character that cfldap uses to separate multiple attribute name/value pairs when more than one attribute is specified in the attribute attribute or the attribute that you want to use has the default delimiter character, which is the semicolon (;), such as mgrpmsgrejecttext;lang-en. The delimiter character is used by the query, add, and modify action attributes, and is used by cfldap to output multi-value attributes. For example, if you use a dollar sign ($), you could specify the following list of name-value pairs with attributes :
"cn = Double Tree Inn$street = 1111 Newbury;Suite 100

Attribute	Description
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 is anonymous.
password	Optional. Password that corresponds to user name.
action	Optional. Specifies the LDAP action. Options : 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, except the distinguished name `dn` attribute. Requires `dn` attribute. See the `modifyType` attribute for additional controls. modifyDN Modifies the distinguished name attribute for LDAP entries on an LDAP server. Requires `dn` attribute. 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"`. Options: oneLevel (default) Searches entries one level below 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 and entries at all levels below 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. 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 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 of the stanza tag within the file that contains the LDAP filter string specification. You can specify an absolute pathname or a simple filename to identify the file. If you use a simple filename, `cfldap` looks for it in ColdFusion's default LDAP directory. The default LDAP directory for a user-installed 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(s) by which to sort query results. Use a comma to separate attributes.
sortControl	Optional. Specifies how to sort query results. Enter one or more of the following values: `nocase` Case-insensitive sort `asc` (default) Ascending case-sensitive sort `desc` Descending case-sensitive sort You can enter a combination of sort types; for example, `sortControl = "nocase`, `asc"`.
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 to insert 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 in a multi-value list of attributes, as follows: `add` Appends the attribute to any existing attributes. `delete` Deletes the attribute from the set of existing attributes. `replace` (default) Replaces an attribute with the specified attribute or attributes. 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 by 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 disable `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 an absolute path or a simple filename. `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 an absolute path or a simple filename. `keyword_db` The password to key database. If you use a simple filename for certificate_db or keyword_db, `cfldap` looks for it in the ColdFusion default LDAP directory location for a user-installed LDAP directory (`C:\cfusion\ldap` for Windows, ). 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 by `cfldap` to output multi-value attributes. The default character is the comma (,). For example, if you set the value of `separator` to a dollar sign (`$`), the `attributes` attribute could have the following value: "objectclass = top$person" where the first value of `objectclass is "top"`, and the second value is `"person"`. Using an alternate character to separate values of an attribute eliminates confusion when the values themselves have commas in them.
delimiter	Optional. Specifies the character that `cfldap` uses to separate multiple attribute name/value pairs when more than one attribute is specified in the `attribute` attribute or the attribute that you want to use has the default delimiter character, which is the semicolon (;), such as `mgrpmsgrejecttext;lang-en`. The delimiter character is used by the `query`, `add`, and `modify` action attributes, and is used by `cfldap` to output multi-value attributes. For example, if you use a dollar sign ($), you could specify the following list of name-value pairs with `attributes` : "cn = Double Tree Inn$street = 1111 Newbury;Suite 100

Usage

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

Variable Names

Description

queryname.recordCount
The 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.

Variable Names	Description
queryname.recordCount	The 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 encrypts the password before transmission.

For CFSSL_CLIENT_AUTH, you do not send a user name and password; authentication is by a digital certificate that you send to the server. CFSSL_CLIENT_AUTH is much more secure; however, it is difficult to administer because all 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 their keys.

Illegal ColdFusion characters can be used in LDAP attribute names. As a result, cfldap could create columns in the query result set whose names contained characters which are illegal in ColdFusion and are, therefore, inaccessible in CFML. In this release of ColdFusion, any illegal characters are automatically mapped to the underscore character. Therefore, column names in the query result set may not exactly match the names of the LDAP attributes.

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>