cfNTauthenticate

Description

Authenticates a user name and password against the Windows NT domain on which the ColdFusion server is running, and optionally retrieves the user's groups.

Category

Security tags

Syntax

<cfNTauthenticate 
username="username" 
password="password" 
domain="nt_domain" 
result="result variable"
listGroups = "yes" or "no"
throwOnError = "yes" or "no">

See also

cflogin, cfloginuser, IsUserInRole, GetAuthUser

History

ColdFusion MX 7: Added this tag.

Attributes

Usage

Use this function to authenticate a user against a Windows NT domain and optionally get the user's groups. This function does not work with the Microsoft Active Directory directory service, and does nothing on UNIX and Linux systems. You typically use this tag inside a cflogin tag to authenticate the user for a cfloginuser tag, as shown in the example.

Note: ColdFusion must run as a user that has the privilege to authenticate other users in the specified domain.

The structure specified in the result attribute contains the following information:

This tag provides two models for handling authentication: status checking and exception handling. If the throwOnError attribute is No, use the result variable's auth and status fields to determine whether the user was authenticated and, if not, the reason for the failure. If the throwOnError attribute is Yes, ColdFusion throws an exception error if the user is not valid. In this case, use try/catch error handling. The catch block must handle any authentication failure.

Example

The following example uses the auth and status fields to determine whether the user is authenticated and the failure cause. It consists of three files that you put in the same directory:

• A main cfntauthexample.cfm page that displays the name if the user is authenticated and contains a logout link.
• A login form page that is displayed if the user is not logged in.
• The Application.cfm page, which contains all the login, authentication, and logout processing code.

For a full description of login processing, see ColdFusion MX Developer's Guide. For information on how this example works, see the comments in the code.

Save the following page as cfntauthenticateexample.cfm. To run the example, request this page in your browser or IDE.

<!--- The Application.cfm page, which is processed each time a user
   requests this page, ensures that you log in first. --->
<cfoutput>
   <h3>Welcome #GetAuthUser()#</h3>
   <!--- A link to log out the user. --->
   <a href="#CGI.script_name#?logout=Yes">Log Out</a> 
</cfoutput>

Save the following page as loginform.cfm:

<!--- A simple login form that posts back to the page whose request initiated
   the login. --->
<H2>Please Log In</H2>
<cfform action="#CGI.script_name#">
   <!--- j_username and j_password are special names that populate cflogin tag
      variables. --->
   User Name: <cfinput type="text" name="j_username" value="cfqa_user1"
      required="Yes"><br>
   Password: <cfinput type="password" name="j_password" value="cfqa_user1"
      required="Yes"><br>
   Domain: <cfinput type="text" name="domain" value="rnd" required="Yes"><br>
   <input type="submit" value="Log In">
</cfform>

Save the following page as Application.cfm:

<!--- If this page is executing in response to the user clicking a logout link,
      log out the user. The cflogin tag code will then run. --->
<cfif IsDefined("URL.logout") AND URL.logout>
   <cflogout>
</cfif>

<!--- The cflogin body code runs only if a user is not logged in. --->
<cflogin>
   <!--- cflogin variable exists only if login credentials are available. --->
   <cfif NOT IsDefined("cflogin")>
      <!--- Show a login form that posts back to the page whose request
      initiated the login, and do not process the rest of this page. --->
      <cfinclude template="loginform.cfm">
      <cfabort>
   <cfelse>
      <!--- Trim any leading or trailing spaces from the username and password 
      submitted by the form. --->
      <cfset theusername=trim(form.j_username)>
      <cfset thepassword=trim(form.j_password)>
      <cfset thedomain=trim(form.domain)>
      <cfntauthenticate username="#theusername#" password="#thepassword#"
         domain="#thedomain#" result="authresult" listgroups="yes">
      <!--- authresult.auth is True if the user is authenticated. --->
      <cfif authresult.auth>
         <!--- Log user in to ColdFusion and set roles to the user's Groups. --->
         <cfloginuser name="#theusername#" password="#thepassword#"
            roles="#authresult.groups#">
      <cfelse>
         <!--- The user was not authenticated. 
               Display an error message and the login form. --->
         <cfoutput>
            <cfif authresult.status IS "AuthenticationFailure">
               <!--- The user is valid, but not the password. --->
               <H2>The password for #theusername# is not correct<br>
                  Please Try again</H2>
            <cfelse>
               <!--- There is one other status value, invalid user name. --->
               <H2>The user name #theusername# is not valid<br>
                  Please Try again</H2>
            </cfif>
         </cfoutput>
         <cfinclude template="loginform.cfm">
         <cfabort>
      </cfif>
   </cfif>
</cflogin>

ColdFusion 9 | ColdFusion 8 | ColdFusion MX 7 | ColdFusion MX 6.1 | ColdFusion MX | Forums | Developer Center | KnowledgeBase | Bug Reporting

Version 7

Comments

Add Comment

remecTim said on Feb 7, 2005 at 4:58 PM :

The attribute "name" is incorrect, and will cause an error. That attribute is actually "username". The sample code has the correct usage.

jrunrandy said on Feb 8, 2005 at 6:53 AM :

remecTim, you are correct and we have entered this as doc bug 59801.

Also, The cfNTauthenticate example is missing number signs around the roles attribute value for the cfloginuser tag. The correct line is as follows:

<cfloginuser name="#theusername#" password="#thepassword#"roles="#authresult.groups#">

This is doc bug 59561.

skibama1 said on Feb 10, 2005 at 4:44 AM :

I wonder if a problem will arise if the user is auto-logged in by IE based on Active Directory crednetials. For example, your web page directory is secured based on AD groups and all your machines are set to auto login by IE based on local intranet security settings. I think this results in the login being recognized by CF before any authentication tags or functions can be run. I guess if I had a specific question with this tag it would be once a user is logged in, based on CF authentication or otherwise, how do you add roles to the roles list?

halL said on Feb 10, 2005 at 2:00 PM :

I believe the following is true, but have not tested it, so I'm not marking it as an answer:

If the Web server uses Active Directory authentication to log a user in, it does not mean that the user is automatically logged into the ColdFusion application security framework.
If you have a cflogin tag, it will still execute.
When the cflogin tag executes, however, it automatically gets a cflogin structure with user's login ID from the web server authentication.

You must still use the cfloginuser tag to log the user into the ColdFusion security framework, and you specify the roles at that time.
The only way to specify roles to the ColdFusion security framework is in the cfloginuser tag.

For an example of using a web server based login with the ColdFusion security framework, see the "Web server-based authentication user security example" section in the Securing Applications chapter of the ColdFusion MX Developer's Guide, at http://livedocs.macromedia.com/coldfusion/7/htmldocs/00001187.htm.
The example starts about 2/3 of the way down on the page.
For more information on ColdFusion MX 7 security, see the rest of the chapter starting at http://livedocs.macromedia.com/coldfusion/7/htmldocs/00001175.htm.

If you need to get information, such as group or role related information, from the Active Directory, you must use the cfldap tag to query the directory.

ajpowellatl said on Jul 7, 2005 at 7:16 AM :

Authentication via Active Directory can be achieved with CFLDAP and is quite effective.

Integrating CFLDAP with AD: http://www.macromedia.com/devnet/server_archive/articles/integrating_cf_apps_w_ms_active_directory.html

This tag will not work with Samba. I have tried using it to authenticate to a server running Mac OS X 10.3 and Samba 3.0. It fails every time with a user not in directory failure. I believe this is more tied to AD than the actual NT login.

Rob_in_KC said on Feb 11, 2008 at 7:45 AM :

If you are not using the listGroups attribute, leave it at its default which is "no". The user will not authenticate if the number of characters returned by listGroups is > 469.

RSS feed | Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/coldfusion/7/htmldocs/00000301.htm

Add Comment