cfauthenticate

Description

Authenticates a user, setting a security context for the application. For more information, see the descriptions of IsAuthenticated and AuthenticatedContext.

Syntax


<cfauthenticate securityContext = "security_context"

  username = "user_ID"

  password = "password"

  setCookie = "Yes" or "No" 

  throwOnFailure = "Yes" or "No"

  authType = "Basic" or "X509">

Attributes

Attribute

Description

securityContext
Required. Security context with which the user is authenticated. This context must be defined in the security system.

username
Required. User to authenticate.

password
Required. User password.

setCookie
Optional. Default is Yes. Indicates whether ColdFusion sets an encrypted cookie to contain authentication information. The cookie's 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.

authType
Optional. Indicates the type of authentication ColdFusion uses.

Basic specifies that authentication uses username/password (default).

X509 specifies that authentication uses X.509 client certificates passed to the Web server from a browser using SSL.

Attribute	Description
securityContext	Required. Security context with which the user is authenticated. This context must be defined in the security system.
username	Required. User to authenticate.
password	Required. User password.
setCookie	Optional. Default is Yes. Indicates whether ColdFusion sets an encrypted cookie to contain authentication information. The cookie's 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.
authType	Optional. Indicates the type of authentication ColdFusion uses. `Basic` specifies that authentication uses username/password (default). `X509` specifies that authentication uses X.509 client certificates passed to the Web server from a browser using SSL.

Usage

Code this tag in the Application.cfm file to set a security context for an 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>

  <cfoutput>

  <!--- Display the message. Alternatively, you might place

   code here to define the user to the security domain. --->

  <P>#cfcatch.message#

  </cfoutput>

 </cfcatch>

 </cftry>

</cfif>

<cfapplication name = "Personnel">

...