User Guide

cfNTauthenticate 309
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>
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
name 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.