MACROMEDIA COLDFUSION 4.5-CFML LANGUAGE, Reference

Page: 41 / 608

Chapter 1: ColdFusion Tags 17
CFAUTHENTICATE
The CFAUTHENTICATE tag authenticates a user, setting a security context for the
application. See the descriptions of the functions
IsAuthenticated and
AuthenticatedContext .
Syntax
<CFAUTHENTICATE SECURITYCONTEXT="context"
USERNAME="user ID"
PASSWORD="password"
SETCOOKIE="yes/no"
THROWONFAILURE="yes/no">
SECURITYCONTEXT
Required. Security context with which the specified user is authenticated. This
context must have been previously defined in the security system.
USERNAME
Required. User to be authenticated.
PASSWORD
Required. Password for the user.
SETCOOKIE
Optional. Default is Yes. Indicates whether ColdFusion sets a cookie to contain
authentication information. This cookie is encrypted and its contents include user
name, security context, browser remote address, and the HTTP user agent.
THROWONFAILURE
Optional. Default is Yes. Indicates whether ColdFusion throws an exception (of
type SECURITY) if authentication fails.
Usage
Code this tag in the Application.cfm file to set a security context for your application.
Call the IsAuthenticated function to determine if the user has been authenticated. If
you specify No for SETCOOKIE, you must call CFAUTHENTICATE for every page in the
application (perhaps in an Application.cfm file).
If you specify THROWONFAILURE=Yes, you can enclose CFAUTHENTICATE in a
CFTRY/CFCATCH block to handle possible exceptions programmatically.
Example
<!--- This example shows the use of CFAUTHENTICATE
in an Application.cfm file --->
<CFIF NOT IsAuthenticated()>
<CFTRY>
<CFAUTHENTICATE SECURITYCONTEXT="Allaire" USERNAME=#user#
PASSWORD=#pwd#>
<CFCATCH TYPE="Security">
<!--- the message to display --->
<H3>Authentication error</H3>