User Guide Cancel

cfldap

Last updated on May 30, 2024 | Also applies to ColdFusion

CFML Reference User Guide
ColdFusion functions
ColdFusion Tags
1. ColdFusion tag summary
2. ColdFusion tags by category
  1. Application framework tags
    1. cfapplication
    2. cfassociate
    3. cferror
    4. cfimport
    5. cfinterface
    6. cflock
    7. cfscript
    8. cfthread
  2. Communications tags
  3. Database manipulation tags
  4. Data output tags
    1. cfchart
    2. cfchartdata
    3. cfchartseries
    4. cfcol
    5. cfcontent
    6. cfdocument
    7. cfdocumentitem
    8. cfdocumentsection
    9. cfflush
    10. cfheader
    11. cflog
    12. cfoutput
    13. cfpresentation
    14. cfpresentationslide
    15. cfpresenter
    16. cfprocessingdirective
    17. cfprint
    18. cfreport
    19. cfreportparam
    20. cfsilent
    21. cftable
  5. Debugging tags
    1. cfdump
    2. cftimer
    3. cftrace
  6. Exception handling tags
    1. cfcatch
    2. cferror
    3. cffinally
    4. cfrethrow
    5. cfthrow
    6. cftry
  7. Extensibility tags
    1. cfchart
    2. cfchartdata
    3. cfchartseries
    4. cfcollection
    5. cfcomponent
    6. cfexecute
    7. cfftp
    8. function
    9. cfindex
    10. cfinterface
    11. cfinvoke
    12. cfinvokeargument
    13. cfobject
    14. cfproperty
    15. cfreport
    16. cfreportparam
    17. cfreturn
    18. cfsearch
    19. cfsharepoint
    20. cfspreadsheet
    21. cfwddx
    22. cfxml
  8. File management tags
    1. cfdirectory
    2. cffile
    3. cffileupload
    4. cfftp
    5. cfzip
    6. cfzipparam
  9. Flow-control tags
    1. cfabort
    2. cfbreak
    3. cfcase
    4. cfcontinue
    5. cfdefaultcase
    6. cfelse
    7. cfelseif
    8. cfexecute
    9. cfexit
    10. cfif
    11. cfinclude
    12. cflocation
    13. cfloop
    14. cfrethrow
    15. cfswitch
    16. cfthrow
    17. cftry
  10. Forms tags
    1. cfapplet
    2. cfcalendar
    3. cffileupload
    4. cfform
    5. cfformgroup
    6. cfformitem
    7. cfgrid
    8. cfgridcolumn
    9. cfgridrow
    10. cfgridupdate
    11. cfinput
    12. cfpdf
    13. cfpdfform
    14. cfpdfformparam
    15. cfpdfparam
    16. cfpdfsubform
    17. cfselect
    18. cfslider
    19. cftextarea
    20. cftree
    21. cftreeitem
  11. Internet Protocol tags
    1. cfajaximport
    2. cfajaxproxy
    3. cfftp
    4. cffeed
    5. cfimap
    6. cfhttp
    7. cfhttpparam
    8. cfldap
    9. cfmail
    10. cfmailparam
    11. cfmailpart
    12. cfpop
    13. cfsprydataset
  12. Page processing tags
    1. cfcache
    2. cfcontent
    3. cfflush
    4. cfheader
    5. cfhtmlhead
    6. cfinclude
    7. cfprocessingdirective
    8. cfsetting
    9. cfsilent
  13. Security tags
  14. Variable manipulation tags
    1. cfcookie
    2. cfdump
    3. cfparam
    4. cfregistry
    5. cfsavecontent
    6. cfschedule
    7. cfset
    8. cfsetting
  15. Other tags
    1. cfimage
    2. cflog
    3. cfregistry
3. Tags a-b
4. Tags c
  1. cfcache
  2. cfcalendar
  3. cfcase
  4. cfcatch
  5. cfchart
  6. cfchartdata
  7. cfchartseries
  8. cfclient
  9. cfclientsettings
  10. cfcol
  11. cfcollection
  12. cfcomponent
  13. cfcontent
  14. cfcontinue
  15. cfcookie
  16. Tags d-e
5. Tags f
6. Tags g-h
  1. cfgraph
  2. cfgraphdata
  3. cfgrid
  4. cfgridcolumn
  5. cfgridrow
  6. cfgridupdate
  7. cfheader
  8. cfhtmlhead
  9. cfhtmltopdf
  10. cfhtmltopdfitem
  11. cfhttp
  12. cfhttpparam
7. Tags i
  1. cfif
  2. cfimage
  3. cfimap
  4. cfimapfilter
  5. cfimpersonate
  6. cfimport
  7. cfinclude
  8. cfindex
  9. cfinput
  10. cfinsert
  11. cfinterface
  12. cfinvoke
  13. cfinvokeargument
8. Tags j-l
9. Tags m-o
10. Tags p-q
  1. cfparam
  2. cfpdf
  3. cfpdfform
  4. cfpdfformparam
  5. cfpdfparam
  6. cfpdfsubform
  7. cfpod
  8. cfpop
  9. cfpresentation
  10. cfpresentationslide
  11. cfpresenter
  12. cfprint
  13. cfprocessingdirective
  14. cfprocparam
  15. cfprocresult
  16. cfprogressbar
  17. cfproperty
  18. cfquery
  19. cfqueryparam
11. Tags r-s
  1. cfregistry
  2. cfreport
  3. cfreportparam
  4. cfrethrow
  5. cfreturn
  6. cfsavecontent
  7. cfschedule
  8. cfscript
  9. cfsearch
  10. cfselect
  11. cfservlet
  12. cfservletparam
  13. cfset
  14. cfsetting
  15. cfsharepoint
  16. cfsilent
  17. cfslider
  18. cfspreadsheet
  19. cfsprydataset
  20. cfstoredproc
  21. cfswitch
12. Tags t
  1. cftable
  2. cftextarea
  3. cftextinput
  4. cfthread
  5. cfthrow
  6. cftimer
  7. cftooltip
  8. cftrace
  9. cftransaction
  10. cftree
  11. cftreeitem
  12. cftry
13. Tags u-z
  1. cfupdate
  2. cfwddx
  3. cfwebsocket
  4. cfwindow
  5. cfxml
  6. cfzip
  7. cfzipparam
CFML Reference
1. Reserved words and variables
2. Ajax JavaScript functions
3. ColdFusion ActionScript functions
4. ColdFusion mobile functions
5. Application.cfc reference
6. Script functions implemented as CFCs
7. ColdFusion Flash Form style reference
8. ColdFusion event gateway reference
9. ColdFusion C++ CFX Reference
10. ColdFusion Java CFX reference
11. WDDX JavaScript Objects
Cloud services

Description

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

Syntax

<cfldap 
action = "action" 
server = "server name" 
attributes = "attribute, attribute" 
delimiter = "delimiter character" 
dn = "distinguished name" 
filter = "filter" 
maxRows = "number" 
modifyType = "replace|add|delete" 
name = "name" 
password = "password" 
port = "port number" 
rebind = "yes|no" 
referral = "number of allowed hops" 
returnAsBinary = "column name, column name" 
scope = "scope" 
secure = "multifield security string" 
separator = "separator character" 
sort = "attribute[, attribute]..." 
sortControl = "nocase|desc|asc" 
start = "distinguished name" 
startRow = "row number" 
timeout = "milliseconds" 
username = "user name"
clientcert = "path to client certificate"
clientcertpassword = "password for the client certificate"
usetls = "true|false">

Note:

You can specify this tag's attributes in an attributeCollection attribute whose value is a structure. Specify the structure name in the attributeCollection attribute and use the tag's attribute names as structure keys.

History

ColdFusion 11: Added 3 new attributes: clientcert, clientcertpassword, and usetls. Removed the filterFile attribute.

ColdFusion 8: Added the ability to use a comma as a delimiter when specifying a list of variables in the returnAsBinary attribute, for example, returnAsBinary="objectGUID,objectSID". Previously, the allowed delimiter was a space.ColdFusion MX 7: Added the returnAsBinary attribute. Added SSL V2 client based authentication; this means that ColdFusion supports the CFSSL_CLIENT_AUTH option. If CFSSL_CLIENT_AUTH is selected, ColdFusion assumes that the first certificate in the cacerts (or the certificate database) contains the Client Certificate.ColdFusion MX:

Changed the name attribute behavior: this tag validates the query name in the name attribute.
Changed sorting behavior: this tag does not support client-side sorting of query results. (It supports server-side sorting; use the sort and sortcontrol attributes.)
Changed how results are sorted: 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.
Deprecated the filterConfig and filterFile attributes. They might not work, and might cause an error, in later releases.

Attributes

Attribute	Req/Opt	Default	Description
action	Required	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.
server	Required		Host name or IP address of LDAP server.
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.
delimiter	Optional	; (semicolon)	Separator between attribute name-value pairs. Use this attribute if either of these situations exist: The attributes attribute specifies more than one item. An attribute contains the default 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 "cn = Double Tree Inn$street = 1111 Elm; Suite 100, where the semicolon is part of the street value.
dn	Required if action = "Add","Modify", "ModifyDN", or "delete"		Distinguished name, for update action, for example, "cn = Bob Jensen, o = Ace Industry, c = US"
filter	Optional	"objectclass = *"	Search criteria for action = "query". List attributes in the form: "(attribute operator value)" For example: "(sn = Smith)"
maxRows	Optional		Maximum number of entries for LDAP queries.
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.
name	Required if action = "Query"		Name of LDAP query. The tag validates the value.
password	Required if secure = "CFSSL_BASIC"		Password that corresponds to user name. If secure = "CFSSL_BASIC", V2 encrypts the password before transmission.
port	Optional	389	Port.
rebind	Optional	no	yes: attempts 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.
returnAsBinary	Optional		A space-delimited list of columns that are to be returned as binary values.
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.
secure	Optional		Security to employ, and required information. If you specify this attribute, its value must be one of the following: CFSSL_BASIC - Provides V2 SSL encryption and server authentication. CFSSL_CLIENT_AUTH - This is mandatory if client certificate based authentication is to be used with CFLDAP tag . This is to be used with clientcert and clientcertpassword.
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.
sort	Optional		Attributes 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".
start	Required if action = "Query"		Distinguished name of entry to be used to start a search.
startRow	Optional	1	Used with action = "query". First row of LDAP query to insert into a ColdFusion query.
timeout	Optional	60000	Maximum length of time, in milliseconds, to wait for LDAP processing.
username	Required if secure = "CFSSL_BASIC"	(anonymous)	User ID.
clientcert	Optional		The full path to the key store file that contains the client certificate.
clientcertpassword	Optional		Password for the client certificate.
usetls	Optional	true/false	Whether to use the startTls extension for initiating SSL over normal LDAP port.

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

If you use the security="CFSSL_BASIC" option, ColdFusion determines whether to trust the server by comparing the server's certificate with the information in the jre/lib/security/cacerts keystore of the JRE used by ColdFusion. The ColdFusion default cacerts file contains information about many certificate granting authorities. If you must update the file with additional information, you can use the keytool utility in the ColdFusion jre/bin directory to import certificates that are in X.509 format. For example, enter the following:

keytool -import -keystore cacerts -alias ldap -file ldap.crt -keypass bl19mq

Then restart ColdFusion. The keytool utility initial keypass password is "change it". For more information on using the keytool utility, see the Sun JDK documentation.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 the Developing ColdFusion Applications.

Note:

Windows only

If the load is high and cfldap produces errors, then chances are that all ephemeral TCP ports are in use. Therefore, no new port can be allocated to a new client connection request.

To resolve the issue, open the registry editor and locate the registry subkey: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters, and add a new entry as shown below:

Value Name: MaxUserPort
Value Type: DWORD
Value data: 65534

Example

<h3>cfldap Example</h3> 
<p>Provides an interface to LDAP directory servers. The example uses the 
University of Connecticut public LDAP server. For more public LDAP servers, 
see <a href="http://www.emailman.com">http://www.emailman.com</a>.</p> 
<p>Enter a name and search the public LDAP resource. 
An asterisk before or after the name acts as a wildcard.</p> 
<!--- If form.name exists, the form was submitted; run the query. ---> 
<cfif IsDefined("form.name")> 
<!--- Check to see that there is a name listed. ---> 
<cfif form.name is not ""> 
<!--- Make the LDAP query. ---> 
<cfldap 
server = "ldap.uconn.edu" 
action = "query" 
name = "results" 
start = "dc=uconn,dc=edu" 
filter = "cn=#name#" 
attributes = "cn,o,title,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">Title</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">#title#</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> 

<form action="#cgi.script_name#" method="POST"> 
<p>Enter a name to search in the database.</p> 
<input type="Text" name="name"> 
<input type="Submit" value="Search" name=""> 
</form>

Note:

Using ldap modifyDN (rename operation) you can move an entry from one point in the tree to another point in the tree. For example, refer to the following scenarios:

To modify the RDN of an entry (within the tree), specify new RDS attribute with value as a key value pair in attributes argument.

<cfldap action="modifyDN" attributes="cn=Accounting Officers" dn="cn=QA Managers,ou=Groups,dc=example,
dc=com" server="localhost" port="10389" username="uid=admin,ou=system" password
="Password@123" >

To move an entry completely to another ldap tree, specify the targetDN in the attributes argument to move the entry to a new location

<cfldap action="modifyDN" attributes="cn=Accounting Managers,ou=Special Users,dc=example,dc=com" 
dn="cn=Accounting Managers,ou=Groups,dc=example,
dc=com" server="localhost" port="10389" username="uid=admin,ou=system" password
="Password@123" >

Get help faster and easier

New user?

cfldap

Description

Category

Syntax

See also

History

Attributes

Usage

Example

Get help faster and easier

Ask the Community

Contact Us