The <cfldap> can be very simple or very complicated. It all depends on what you're looking to do and how you want to authenticate your users.

For quite some time I wanted to authenticate the users on my intranet through Active Directory. I spent countless hours searching the Web for someone to explain the basics in a way I could understand being a basic ColdFusion developer. Most articles and tutorials I came across were for intermediate or advanced users.

I wound up learning most of it on my own after getting an LDAP browser and snooping around in Active Directory for what I was looking for. To my surprise accessing Active Directory wasn't as complicated as it may seem. There are tutorials out on the Web that show you different ways to access Active Directory and references that show the different attributes of Active Directory that you can query.

Every time I ask someone about accessing Active Directory using the <cfldap> tag, they're like "No Way, that's too complicated for me." Or they respond with "I know nothing about Active Directory."

Well, this article will show you how to authenticate through Active Directory with little or no <cfldap> or Active Directory experience.

I have a Windows 2000 Server and Windows 2003 Server and had to change my code for each domain because of the differences in Active Directory. Trial and error led me to find a way to use the same code for both Windows 2000 and Windows 2003 domain controllers, so I decided to pass on my knowledge.

<cfldap> can be very simple or very complicated. It all depends on what you're looking to do and how you want to authenticate your users. I'm going to show you how you can use <cfldap> to authenticate your users using just the basics. Nothing complicated!

Let's Get Started
First you should understand the basics of the <cfldap> tag. Im only going to show you the basic options to use for this example.

First let's assume that I have a domain controller called "ns1" and my domain is "adtest.com."

Here's a snapshot of a cfldap query that I used to find a user in my Active Directory:

<cfldap action="QUERY"
   name="GetUserInfo"
   attributes="dn"
   start="dc=adtest,dc=com"
   scope="subtree"
   filter="(&(objectclass=user)(samaccountname=#form.cfusername#))"
   server="ns1.adtest.com"
   username="administrator@adtest.com"
   password="password"
>

Let's start with the attributes, the attributes are the information that we want to query from Active Directory. Think of this like a "Select" statement in a regular query. In this case we just want "dn". (distinguishedName).

In the start field, you only need to define the "dc" (dc means domain content rather than domain controller in this context). Notice I used "adtest" as the first dc and "com" as the second dc. So if you have a .NET domain, just replace the dc="com" with dc="net."

The next item is the "scope." I think this is where some users make the mistake of not defining. The first time I tried to access my Active Directory I thought I didn't need to define the "scope." My Active Directory is set up with many OUs and with about three levels. The default option for "scope" is "onelevel." If you let it default you will only be querying one level below entry. So in my case, users within the one-level OUs could authenticate just fine; the other users could not. Imagine my headache figuring that out!"

So now I like to use the "subtree" option. The "subtree" option queries the entry and all levels below it.

The next item is filter. In the cfldap query above notice that I used the "objectclass=user." This is what we are querying for. If I just wanted to query the Active Directory for a computer name, I would have "computer" instead of "user." There are many other objectclass types to choose from, but I don't want to confuse you with objectclasses we don't need for this example.

The next filter is the samaccountname. This is the same account name as in the Windows Active Directory. It's basically the user login name. Here we put the login name that came from the form (#form.cfusername#).

Next is the "server." This is straightforward. Just put in your complete server name including the domain name like this "ns1.adtest.com".

The username is where I found the difference between Windows 2000 and Windows 2003 domain controllers. Windows 2000 requires you to have the "@adtect.com" at the end of all names and Windows 2003 doesn't. I found that if I just add it into my code like I did above I wouldn't have to worry about either domain since Windows 2003 accepts it. Notice that I used the administrator to authenticate to Active Directory. You can use whatever username and password you want that has access rights to query your Active Directory.

What this query does is find the user in the Active Directory. It does a lookup to determine if there's a samaccountname that matches the #form.cfusername#. If the user exists then we can move on to the next section. If not, then we should kick an error saying that the username wasn't found. I do a recordcount against the "GetUserInfo" query. If it comes back with a 0, then it didn't find the user in AD.

Authenticating a User
Okay, here we're going to assume we got a 1 with our recordcount "cfif" statement. Here's the next query example that actually authenticates the user:

<cfif #getuserinfo.recordcount# gt 0>
  <cftry>
   <cfldap action="QUERY"
   name="AuthenticateUser"
   attributes="givenname,samaccountname,dn,cn,mail"
   start="dc=adtest,dc=com"
   maxrows="1"
   scope="subtree"
   filter="(&(objectclass=user)(samaccountname=#form.cfusername#))"
   server="ns1.adtest.com"
   username="#form.cfusername#@adtest.com"
   password="#form.cfpassword#">
   <cfset LoginMessage = "User Authentication Passed">
   <cfcatch type="any">
   <cfset LoginMessage = "User Authentication Failed">
   </cfcatch>
  </cftry>
<cfelse>
   <cfset LoginMessage = "Username not found">
</cfif>