<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">
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.
Category
Internet Protocol tags
See also
cfftp,
cfhttp,
cfmail,
cfmailparam,
cfpop
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,keyword_db"
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.
|
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>