cfldap

The authentication lesson checked a submitted username and password against your own users table. A lot of real enterprise applications don't have their own user table at all, they authenticate against a company's existing directory server, commonly Microsoft Active Directory, over LDAP (Lightweight Directory Access Protocol). cfldap is ColdFusion's interface to that.

Learning Objectives

After completing this lesson, you'll be able to:

• Explain what an LDAP directory and a distinguished name (DN) actually are.
• Query directory entries with cfldap action="query".
• Authenticate a user against Active Directory instead of your own table.
• Add, modify, and delete directory entries.
• Prevent LDAP injection in a filter built from user input with encodeForLDAP().

What an LDAP Directory Actually Is

An LDAP directory is a hierarchical database of entries, think of it like a folder tree, where every entry (a user, a group, a computer) has a unique path called a distinguished name (DN), such as cn=John Smith,ou=Sales,dc=example,dc=com. Reading that right to left: dc=example,dc=com is the domain, ou=Sales is an organizational unit (a folder) inside it, and cn=John Smith is the specific entry.

How a cfldap Query Flows

Querying Directory Entries

<cfldap server="ldap.example.com"
    port="389"
    action="query"
    name="results"
    start="dc=example,dc=com"
    scope="subtree"
    filter="(sn=Smith)"
    attributes="cn,sn,givenName,mail,title">

<cfoutput query="results">
    #cn# - #mail#<br>
</cfoutput>

Key Attributes

A Real Example: Authenticating Against Active Directory

Instead of hashing a password and comparing it to your own users table, the query itself IS the authentication check here: if the bind (the connection using the submitted username and password) succeeds and a matching entry comes back, the credentials were correct. This is Adobe's own documented pattern for checking a login against Active Directory.

cfldap(
    server = "ldap.mycompany.com",
    port = 636,
    action = "QUERY",
    name = "qLDAPLookup",
    secure = "CFSSL_BASIC",
    username = "MYDOMAIN\" & encodeForLDAP(arguments.username),
    password = arguments.password,
    start = "dc=mycompany,dc=com",
    attributes = "cn,userPrincipalName,title,mail",
    filter = "(sAMAccountName=" & encodeForLDAP(arguments.username) & ")"
);

if (qLDAPLookup.recordCount EQ 1) {
    // Credentials were valid, the bind succeeded and found exactly one matching user
    cfloginuser(name = arguments.username, password = arguments.password, roles = "employee");
}

Adding, Modifying, and Deleting Entries

<cfldap action="modify"
    server="ldap.example.com"
    dn="cn=John Smith,ou=Sales,dc=example,dc=com"
    attributes="title=Senior Sales Manager"
    modifytype="replace">

Handling Special Characters in Attribute Values

When an attribute value itself contains a comma or semicolon, those characters collide with the characters cfldap normally uses to separate multiple values and multiple attribute pairs. separator and delimiter let you pick different characters instead, exactly for this case, per Adobe's own advanced topics documentation.

<cfldap action="add"
    server="ldap.example.com"
    dn="cn=Example Inc,ou=Companies,dc=example,dc=com"
    attributes="o=Example, Inc.|description=Sales; Marketing"
    separator="|">

Common Beginner Mistakes

Best Practices

• Always wrap user input going into a filter with encodeForLDAP().
• Use secure="CFSSL_BASIC" (port 636) rather than plain LDAP for any connection carrying credentials.
• Use scope="subtree" when searching needs to cover an entire branch, not just its immediate children.
• Wrap cfldap authentication calls in cftry/cfcatch, since a failed bind commonly throws rather than returning an empty result.

Interview Questions

Summary

In this lesson, you queried an LDAP directory with cfldap, authenticated a user against Active Directory by using their submitted credentials as the bind itself, added/modified/deleted directory entries, and covered a real security practice: encoding user input with encodeForLDAP() before it goes into a filter, to prevent LDAP injection.

What's Next?

The next lessons cover cfcollection, cfindex, and cfsearch: building and querying a full-text search collection directly from ColdFusion.