cfNTauthenticate ColdFusion 9 Documentation

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.

Syntax

<cfNTauthenticate  
    domain="NT domain"  
    password="password"  
    username="user name"  
    listGroups = "yes|no" 
    result="result variable" 
    throwOnError = "yes|no">

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 MX 7: Added this tag.

Attributes

Attribute	Req/Opt	Default	Description
`domain`	Required		Domain against which to authenticate the user. The ColdFusion J2EE server must be running on this domain.
`password`	Required		User’s password.
`username`	Required		User’s login name.
`listGroups`	Optional	No	Boolean value that specifies whether to include a comma-delimited list of the user’s groups in the result structure.
`result`	Optional	`cfntauthenticate`	Name of the variable in which to return the results.
`throwOnError`	Optional	`no`	Boolean value that specifies whether to throw an exception if the validation fails. If this attribute is `yes`, ColdFusion throws an error if the username or password is invalid; the application must handle such errors in a try/catch block or ColdFusion error handler page.

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 the example shows.

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:

Field	Value
`auth`	Whether the user is authenticated: `yes` `no`
`groups`	A comma-delimited list of the user’s groups in the specified domain. The structure includes this field only if the `listGroups` attribute is `yes`.
`name`	The user name; equals the tag’s `username` attribute.
`status`	The authentication status. One of the following: `success` `UserNotInDirFailure`: the user is not listed in the directory. `AuthenticationFailure`: the user is in the directory, but the password is not valid.

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 the Developing ColdFusion Applications. 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>

cfNTauthenticate