Using Operating System Security

We've seen how you can roll your own security system so that authentication can be performed in multiple fashions. You can use a database lookup, LDAP, or any other method. One that may be particularly useful is the operating system itself. If your ColdFusion server runs on a Windows machine using domains, ColdFusion allows you to authenticate against any domain. You can not only authenticate a user, you can get a list of groups the user is a member of. This is all possible with the new, <cfNTAuthenticate> tag. Table 21.4 lists the attributes for this tag.

Table 21.4. <cfNTAuthenticate> Tag Attributes

ATTRIBUTE	PURPOSE
name	Required. Username to authenticate.
password	Required. Passsword to authenticate.
domain	Required. The domain that the user belongs to. ColdFusion must be running on a box that has access to this domain.
result	Optional. Specifies the name of a variable that will contain the result of the authentication attempt. This structure will contain an auth key that indicates if the user was authenticated, a groups key that lists the groups the user is a member of (if the listGroups attribute is used), and a status value. Status will either be: success, UserNotInDirFailure (the user isn't a member of the domain), AuthenticationFailure (password failure).
listGroups	Optional. If true, the user's groups will be returned in the structure specified by the result attribute. The default value is false.
tHRowOnError	Optional. Specifies if the tag should throw an exception if the authentication fails. This defaults to false.

Listing 21.10 demonstrates a simple example of using <cfNTAuthenticate>. I'm keeping this example very simple since it will only run on Windows machines, and only those machines that are part of a domain. Obviously you will need to modify the username and password values.

Listing 21.10. DomainAuth.cfmUsing <cfNTAuthenticate>

 <!---  Filename: DomainAuth.cfm  Created by: Raymond Camden ([e-mail])  Purpose: Uses <cfNTAuthenticate> ---> <!--- Change this username! ---> <cfset username="changeme"> <!--- Change this password! ---> <cfset password="changeme"> <!--- Change this domain! ---> <cfset domain="changeme"> <!--- Attempt to logon ---> <cfNTAuthenticate username="#username#" password="#password#" result="result"  domain="#domain#" listGroups="yes"> <cfdump var="#result#" label="Result of NT authentication."> 

The script begins by creating variables for the three main pieces needed for authentication, username, password, and domain. As it obviously states in the code, you will need to change these values. However, if you want to see a failed authentication result, you can leave these alone. Finally, we run the <cfNTAuthenticate> tag, passing in the values and telling it to return the result in a struct called result and enumerating the groups the user belongs to. Lastly we dump the result structure. Again, you will have to modify the values in order to get a valid authentication result.