cfldap

Description

Provides an interface to a Lightweight Directory Access Protocol (LDAP) directory server, such as the Netscape Directory Server.

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

History

New in ColdFusion MX:

This tag validates the query name in the name attribute.
This tag does not support client-side sorting of query results. (It supports server-side sorting; use the sort and sortcontrol attributes.)
Server-side sorting results might be sorted slightly differently than in ColdFusion 5. If you attempt a sort against a server that does not support it, ColdFusion MX throws an error.
The filterconfig and filterfile attributes are deprecated. Do not use them in new applications. They might not work, and might cause an error, in later releases. If they are used, this tag throws an exception.

Attributes

Attribute Req/Opt Default Description

server
Required

Host name or IP address of LDAP server.

port
Optional
389
Port

username
Required if secure = "CFSSL_BASIC"
(anonymous)
User ID

password
Required if secure = "CFSSL_BASIC"

Password that corresponds to user name.
If secure = "CFSSL_BASIC", V2 encrypts the password before transmission.

action
Optional
query

query: returns LDAP entry information only. Requires name, start, and attributes attributes.

add: adds LDAP entries to LDAP server. Requires attributes attribute.

modify: modifies LDAP entries, except distinguished name dn attribute, on LDAP server. Requires dn. See modifyType attribute.

modifyDN: modifies distinguished name attribute for LDAP entries on LDAP server. Requires dn.

delete: deletes LDAP entries on an LDAP server. Requires dn.

name
Required if action = "Query"

Name of LDAP query. The tag validates the value.

timeout
Optional
60
Maximum length of time, in seconds, to wait for LDAP processing.

maxRows
Optional

Maximum number of entries for LDAP queries.

start
Required if action = "Query"

Distinguished name of entry to be used to start a search.

scope
Optional
oneLevel
Scope of search, from entry specified in start attribute for action = "Query".

oneLevel: entries one level below entry.

base: only the entry.

subtree: entry and all levels below it.

attributes
Required if action = "Query", "Add", "ModifyDN", or "Modify"

For queries: comma-delimited list of attributes to return. For queries, to get all attributes, specify "*".
If action = "add" or "modify", you can specify a list of update columns. Separate attributes with a semicolon.
If action = "ModifyDN", ColdFusion passes attributes to the LDAP server without syntax checking.

filter
Optional
"objectclass = *"
Search criteria for action = "query".
List attributes in the form:
"(attribute operator value)" Example: "(sn = Smith)"

sort
Optional

Attribute(s) by which to sort query results. Use a comma delimiter.

sortControl
Optional
asc

nocase: case-insensitive sort

asc: ascending (a to z) case-sensitive sort

desc: descending (z to a) case-sensitive sort

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

dn
Required if action = "Add", "Modify", "ModifyDN", or "delete"

Distinguished name, for update action. Example: "cn = Bob Jensen, o = Ace Industry, c = US"

startRow
Optional
1
Used with action = "query". First row of LDAP query to insert into a ColdFusion query.

modifyType
Optional
replace
How to process an attribute in a multi-value list.

add: appends it to any attributes

delete: deletes it from the set of attributes

replace: replaces it with specified attributes

You cannot add an attribute that is already present or that is empty.

rebind
Optional
No

Yes: attempt to rebind referral callback and reissue query by referred address using original credentials.

No: referred connections are anonymous

referral
Optional

Integer. Number of hops allowed in a referral. A value of 0 disables referred addresses for LDAP; no data is returned.

secure
Optional

Security to employ, and required information. One option:

CFSSL_BASIC; certificate_db

"CFSSL_BASIC" provides V2 SSL encryption and server authentication

-certificate_db: certificate database file (Netscape cert7.db format). Absolute path or simple filename. See the Usage section.

separator
Optional
, [comma]
Delimiter to separate attribute values of multi-value attributes. Used by query, add, and modify actions, and by cfldap to output multi-value attributes.
For example, if $ (dollar sign), the attributes attribute could be "objectclass = top$person", where the first value of objectclass is "top", and the second value is "person". This avoids confusion if values include commas.

delimiter
Optional

Separator for attribute name-value pairs, if:

the attributes attribute specifies more than one item

an attribute has the delimiter semicolon. For example: mgrpmsgrejecttext;lang-en

Used by query, add, and modify actions, and by cfldap to output multi-value attributes.
For example, if $ (dollar sign), you could specify this list of pairs with attributes:
"cn = Double Tree Inn$street = 1111 Elm;Suite 100

Attribute	Req/Opt	Default	Description
server	Required		Host name or IP address of LDAP server.
port	Optional	389	Port
username	Required if `secure` = `"CFSSL_BASIC"`	(anonymous)	User ID
password	Required if `secure` = `"CFSSL_BASIC"`		Password that corresponds to user name. If `secure = "CFSSL_BASIC"`, V2 encrypts the password before transmission.
action	Optional	query	`query`: returns LDAP entry information only. Requires `name`, `start`, and `attributes` attributes. `add`: adds LDAP entries to LDAP server. Requires `attributes` attribute. `modify`: modifies LDAP entries, except distinguished name `dn` attribute, on LDAP server. Requires `dn`. See `modifyType` attribute. `modifyDN`: modifies distinguished name attribute for LDAP entries on LDAP server. Requires `dn`. `delete`: deletes LDAP entries on an LDAP server. Requires `dn`.
name	Required if action = "Query"		Name of LDAP query. The tag validates the value.
timeout	Optional	60	Maximum length of time, in seconds, to wait for LDAP processing.
maxRows	Optional		Maximum number of entries for LDAP queries.
start	Required if action = "Query"		Distinguished name of entry to be used to start a search.
scope	Optional	oneLevel	Scope of search, from entry specified in `start` attribute for `action = "Query"`. oneLevel: entries one level below entry. base: only the entry. subtree: entry and all levels below it.
attributes	Required if `action = "Query", "Add", "ModifyDN"`, or `"Modify"`		For queries: comma-delimited list of attributes to return. For queries, to get all attributes, specify `"*"`. If `action = "add"` or `"modify"`, you can specify a list of update columns. Separate attributes with a semicolon. If `action = "ModifyDN"`, ColdFusion passes attributes to the LDAP server without syntax checking.
filter	Optional	"objectclass = *"	Search criteria for `action = "query"`. List attributes in the form: `"(attribute operator value)"` Example: `"(sn = Smith)"`
sort	Optional		Attribute(s) by which to sort query results. Use a comma delimiter.
sortControl	Optional	asc	nocase: case-insensitive sort asc: ascending (a to z) case-sensitive sort desc: descending (z to a) case-sensitive sort You can enter a combination of sort types; for example, `sortControl = "nocase, asc"`.
dn	Required if `action = "Add", "Modify", "ModifyDN", or "delete"`		Distinguished name, for `update` action. Example: `"cn = Bob Jensen, o = Ace Industry, c = US"`
startRow	Optional	1	Used with `action = "query"`. First row of LDAP query to insert into a ColdFusion query.
modifyType	Optional	replace	How to process an attribute in a multi-value list. add: appends it to any attributes delete: deletes it from the set of attributes replace: replaces it with specified attributes You cannot add an attribute that is already present or that is empty.
rebind	Optional	No	Yes: attempt to rebind referral callback and reissue query by referred address using original credentials. No: referred connections are anonymous
referral	Optional		Integer. Number of hops allowed in a referral. A value of 0 disables referred addresses for LDAP; no data is returned.
secure	Optional		Security to employ, and required information. One option: CFSSL_BASIC; certificate_db "CFSSL_BASIC" provides V2 SSL encryption and server authentication -certificate_db: certificate database file (Netscape cert7.db format). Absolute path or simple filename. See the Usage section.
separator	Optional	, [comma]	Delimiter to separate attribute values of multi-value attributes. Used by `query`, `add`, and `modify` actions, and by `cfldap` to output multi-value attributes. For example, if `$` (dollar sign), the `attributes` attribute could be `"objectclass = top$person"`, where the first value of objectclass is "`top`", and the second value is "`person`". This avoids confusion if values include commas.
delimiter	Optional		Separator for attribute name-value pairs, if: the `attributes` attribute specifies more than one item an attribute has the delimiter semicolon. For example: `mgrpmsgrejecttext;lang-en` Used by `query`, `add`, and `modify` actions, and by `cfldap` to output multi-value attributes. For example, if `$` (dollar sign), you could specify this list of pairs with attributes: `"cn = Double Tree Inn$street = 1111 Elm;Suite 100`

Usage

If you use the query action, cfldap creates a query object, allowing access to information in the query variables, as follows:

Variable name Description

queryname.recordCount
Number of records returned by query

queryname.currentRow
Current row of query that cfoutput is processing

queryname.columnList
Column names in query

Variable name	Description
queryname.recordCount	Number of records returned by query
queryname.currentRow	Current row of query that `cfoutput` is processing
queryname.columnList	Column names in query

To use the security = "CFSSL_BASIC" option, you must copy the cert7.db and/or key3.db key files to the default directory location of a user-installed LDAP directory; on Windows, the directory is C:\cfusion\ldap.

The security certificate encrypts conversation. The server always sends a digital certificate to confirm the server.

Characters that are illegal in ColdFusion can be used in LDAP attribute names. As a result, the cfldap tag could create columns in the query result set whose names contain illegal characters and are, therefore, inaccessible in CFML. In ColdFusion, illegal characters are automatically mapped to the underscore character; therefore, column names in the query result set might not exactly match the names of the LDAP attributes.

For usage examples, see Developing ColdFusion MX Applications with CFML.

Example

<h3>cfldap Example</h3>
<p>Provides an interface to LDAP 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>