|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Using Advanced Security in Application Pages
|
|
|
|
After you set up the security context, rules, and policies for your application, you can use security in application pages. This section describes how developers use security tags and functions to authenticate users and provide or withhold resources according to the security context's rules.
- You can use CFAUTHENTICATE on any application page, or on the Application.cfm file for your application, to authenticate users (in other words, to make sure they are who they say they are, and are allowed to use this security context). Pass this information to subsequent pages, where you can test for authentication.
ColdFusion sets a cookie, CFAUTH, to contain authentication information. If
you choose not to use this cookie, you must check authentication for each
request.
- The IsAuthenticated function checks to see if the current user is authenticated.
- The IsAuthorized function checks to see if the user is authorized for certain resources.
|
|
|
|
Encrypting application pages
|
|
|
You can encrypt strings using the Encrypt and Decrypt functions. See the CFML Language Reference for descriptions of these functions.
|
|
|
|
CFAUTHENTICATE syntax |
|
|
|
The CFAUTHENTICATE tag has several required attributes:
- SECURITYCONTEXT-- Describes which security context to use for authentication and authorization. This name matches the security context as defined in the Advanced Security page of the Administrator.
- USERNAME -- The username required to access the protected resources.
- PASSWORD -- The password required to access the protected resources.
The USERNAME and PASSWORD are usually variables passed in a cookie from form fields on a secure login page for the current session.
In addition, CFAUTHENTICATE has two optional attributes:
- SETCOOKIE -- Indicates whether ColdFusion sets a cookie to contain authentication information. This cookie is encrypted and includes the user name, security context, browser remote address, and the http user agent. Default is Yes.
- THROWONFAILURE -- Indicates whether ColdFusion throws an exception of type Security if authentication fails. Default is Yes.
|
|
|
|
Example
|
|
|
<CFAUTHENTICATE SECURITYCONTEXT="SecurityContextName"
USERNAME=#userID#
PASSWORD=#pwd#>
If the user has not already been defined in the system, a ColdFusion Security exception is thrown. You can either reject access to the resource or re-route the user to a login page. For example, you can display a login form and then pass the user along to the originally-requested page.
For information on exception handling strategies in ColdFusion, see Chapter 9, Structured Exception Handling.
See the CFML Language Reference for a full description of the CFAUTHENTICATE tag.
|
|
|
|
Authentication and Authorization functions |
|
|
|
After using CFAUTHENTICATE to check if the user is defined for the security context, you can use two security functions:
- IsAuthenticated checks to see if the current session has been authenticated by the CFAUTHENTICATE tag.
- IsAuthorized checks whether the authenticated user has access to the named resource, based on rules defined in the security context.
|
|
|
|
IsAuthenticated Syntax
|
|
|
The IsAuthenticated function returns TRUE if the user has been authenticated for the current request; otherwise, it returns FALSE.
The IsAuthenticated function does not take any parameters. Instead it checks whether a CFAUTHENTICATE tag has been successfully executed for the current request. If not, if looks for the CFAUTH cookie to determine if the user is authenticated or not.
If you choose not to set a cookie in CFAUTHENTICATE (by specifying SETCOOKIE="No" in CFAUTHENTICATE), you must call CFAUTHENTICATE for every request in the application.
|
|
|
|
IsAuthorized Syntax
|
|
|
Once a user is authenticated, you can use the IsAuthorized function to check which resources the user is allowed to access.
IsAuthorized returns TRUE if the user is authorized to perform the specified action on the specified ColdFusion resource. IsAuthorized takes three parameters:
IsAuthorized(ResourceType, ResourceName, [ResourceAction])
For example, to check whether the authenticated user is authorized to update a datasource resource called orders, use this syntax:
IsAuthorized("Datasource", "orders", "update")
The IsAuthorized function returns TRUE if the user is authorized for the named Datasource, or if the Datasource is not protected in the security context.
|
|
|
|
Note
|
|
|
The ColdFusion server only checks to see if a user is authorized when a developer specifically requests it with the IsAuthorized function. It is up to the developer to decide what action to take based on the results of the IsAuthorized call.
See the CFML Language Reference for full descriptions of the IsAuthorized and IsAuthenticated functions.
|
|
|
|
Catching security exceptions |
|
|
|
You can use the structured exception handling tags, CFTRY and CFCATCH, to catch security exceptions. Setting the TYPE attribute in CFCATCH to "Security" enables you to catch failures in the CFAUTHENTICATE tag. You can also catch catastrophic failures from the IsAuthorized or IsAuthenticated functions.
Set the THROWONFAILURE attribute to Yes and enclose the CFAUTHENTICATE tag in a CFTRY/CFCATCH block if you want to handle possible exceptions programmatically.
For information on exception handling strategies in ColdFusion, see Chapter 9, Structured Exception Handling.
|
|
|
|
Example
|
|
|
<!--- This exaple shows the use of excpetion handling
with CFAUTHENTICATE in an Application.cfm file --->
<HTML>
<HEAD>
<TITLE>CFAUTHENTICATE Example</TITLE>
</HEAD>
<BODY>
<H3>CFAUTHENTICATE Example></H3>
<P>The CFAUTHENTICATE tag authenticates a user and
sets the security context for an application.
<P>Code this tag in the Application.cfm file to set a
security context for your application.
<P>If the user has not already been defined in the
system, you can either reject the page, request that
the user respecify the username and password, or define
a new user.
<!--- This code is from an Application.cfm file --->
<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 context. --->
<P>#CFCATCH.Message#
</CFOUTPUT>
</CFCATCH>
</CFTRY>
<CFAPPLICATION NAME="Personnel">
</BODY>
</HTML>
|
|
|
  
|
|
|
AllaireDoc@allaire.com
Copyright © 1998, Allaire Corporation. All rights reserved.
|