Developing ColdFusion MX Applications with CFML
Securing Applications

About user security

User security lets your application use security rules to determine what it displays. It has two elements:

• Authentication
• Authorization

Authentication ensures that a valid user is logged in, based on an ID and password provided by the user. ColdFusion maintains the user ID information while the user is logged in.

Authorization ensures that the logged-in user is allowed to use a page or perform an operation. Authorization is typically based on one or more roles (sometimes called groups) to which the user belongs. For example, in an employee database, all users could be members of either the employee role or the contractor role. They could also be members of roles that identify their department, position in the corporate hierarchy, or job description. For example, someone could be a member of some or all of the following roles:

• Employees
• Human Resources
• Benefits
• Managers

Roles enable you to control access in your application resources without requiring the application to maintain knowledge about individual users. For example, suppose you use ColdFusion for your company's intranet. The Human Resources department maintains a page on the intranet on which all employees can access timely information about the company, such as the latest company policies, upcoming events, and job postings. You want everyone to be able to read the information, but you want only certain authorized Human Resources employees to be able to add, update, or delete information.

Your application gets the user's roles from the user information data store at log in, and then enables access to specific pages or features based on the roles. Typically, you store user information in a database, LDAP directory, or other secure information store.

You can also use the user ID for authorization. For example, you might want to let employees view customized information about their salaries, job levels, and performance reviews. You certainly would not want one employee to view sensitive information about another employee, but you would want managers to be able to see, and possibly update, information about their direct reports. By employing both user IDs and roles, you can ensure that only the appropriate people can access or work with sensitive data.

The following figure shows a typical flow of control for user authentication and authorization. Following sections expand on this diagram to describe how you implement user security in ColdFusion.

Security tags and functions

ColdFusion provides the following tags and functions for user security:

Tag or function	Purpose
cflogin	A container for user authentication and login code. The body of the tag runs only if there is no logged-in user. When using application-based security, you put code in the body of the cflogin to check the user-provided ID and password against a data source, LDAP directory, or other repository of login identification. The body includes a cfloginuser tag (or a ColdFusion page that contains a cfloginuser tag) to establish the authenticated user's identity in ColdFusion.
cfloginuser	Identifies the authenticated user to ColdFusion. Specifies the user's ID, password, and roles. Typically used inside cflogin tags. The cfloginuser tag requires three attributes, name, password, and roles, and does not have a body. The roles attribute is a comma- delimited list of role identifiers to which the logged-in user belongs. All spaces in the list are treated as part of the role names, so you should not follow commas with spaces.
cflogout	Logs out the current user. Removes knowledge of the user ID and roles from the server. If you do not use this tag, the user is automatically logged out when the session ends. The cflogout tag does not take any attributes, and does not have a body.
cffunction	Used only in cfcomponent tags. If you include a roles attribute, the function executes only when there is a logged in user who belongs to one of the specified roles.
IsUserInRole	Returns True if the current user is a member of the specified role.
GetAuthUser	Returns the ID of the current logged in user.

About web server authentication and application authentication

ColdFusion supports two forms of user authentication:

• Web server basic authentication
• Application authentication

About web server basic authentication

All major web servers support basic authentication, also known as basic HTTP authentication. The web server requires the user to log in to access pages in a particular directory, as follows:

1. When the user first request a page in the secured directory, the web server presents the user with a login page
2. The user fills in the login page and submits it
3. The web server checks the user's login ID and password using its own user authentication mechanism.
4. If the user logs in successfully, the browser caches the authentication information and sends it with every subsequent page request from the user.
5. The web server processes the requested page and all future page requests from the browser that contain the cached login information, if it is valid for the requested page.

The application can perform additional authorization checks based on the information provided by the browser with each request. For example, the application can determine the user's roles based on the login ID and check the roles against specific roles required to access pages or sections of code within pages.

You can use basic web server authentication without using any ColdFusion security features. In this case, you only perform directory-based user authentication, and you configure all user security through the web server's interfaces. You do not use any of the ColdFusion security features, and typically do not perform role-based authorization.

You can also use basic web server authentication with ColdFusion security tags and functions to enforce user authorization. In this case you rely on the web server for user authentication, and your application does not have to display a login page. You then use the web server authentication information with the cflogin and cfloginuser tags to log the user into the ColdFusion user security system and use the IsUserInRole and GetUserName functions to ensure user authorization. For more information on this form of security, see "A basic authentication security scenario".

About application authentication

With application authentication, you do not rely on the web server to enforce application security. The application performs all user authentication and authorization. The application displays a login page, checks the user's identity and login against its own authorization store, such as an LDAP directory or database, and logs the user into ColdFusion using the cfloginuser tag. The application can then use the IsUserInRole and GetUserName functions to check the user's roles or identity before running a ColdFusion page or specific code on a page. For more information on application authentication, see "An application authentication security scenario".

Controlling ColdFusion login behavior

When you use the cfloginuser tag within a cflogin tag, ColdFusion stores a login token in a memory-only browser cookie. Therefore, to use the cflogin tag to check for an authenticated user, the user must enable memory-only cookies in the browser. The login cookie does not lasts after the user closes the browser.

You can use the cfloginuser tag without user cookies, but the login information remains in effect for only the current page. For more information on user logins without cookies, see "Using ColdFusion security without cookies".

The cflogin tag has three optional arguments that control the characteristics of a ColdFusion login, as follows:

Attribute	Use
idleTimeout	If no page requests occur during the idleTiemout period, the ColdFusion logs the user out. The default is 1800 seconds (30 minutes).
applicationToken	Limits the login validity to a specific application as specified by a ColdFusion page's cfapplication tag. The default value is the current application name.
cookieDomain	The Internet domain for which the ColdFusion security cookie is valid. By default, there are no domain limitations.

Logging a user out

After a user logs in, the ColdFusion user authorization and authentication information remains valid until any of the following happens:

• The login times out. This happens if the user does not request a new page for the idleTimeout period.
• The application uses a cflogout tag to log out the user, usually in response to the user clicking a logout link or button.
• The user closes the browser.

Specifying an applicationToken value

The login identification created by cflogin tag is valid only for pages within the directory that contains the cflogin tag and any of its subdirectories. Therefore, if a user requests a page in another directory tree, the current login credentials are not valid for accessing those pages. This security limitation lets you use the same user names and passwords for different sections of your application (for example, a UserFunctions tree and a SecurityFunctions tree) and enforce different roles to the users depending on the section.

ColdFusion uses the applicationToken value to generate a unique identifier that enforces this rule. The default applicationToken value is the current application name, as specified by a cfapplication tag. In normal usage, there you do not need to specify a applicationToken value in the cflogin tag.

Limiting the valid internet domain

Use the cookieDomain attribute to limit the log-in capabilities to users from a specific domain or even a specific system. For example, to ensure that only users located in the macromedia.com domain can log in to your application, specify cookieDomain=".macromedia.com". To specify a domain name, you start the name with a period.

The cflogin structure

The cflogin tag has a built-in cflogin structure that contains two variables: cflogin.name and cflogin.password. These variables contain the user ID and password in either of the following cases:

• The cflogin tag body is executing in response to a user logging in on the browser's basic login page.
• The cflogin tag body is executing in response to a user logging in on an application login form that contains input fields with the names j_username and j_password.

Therefore, the cflogin structure provides a consistent interface for determining the user's login ID and password independent of the technique you use for displaying the login form.

Using ColdFusion security without cookies

You can implement a limited-lifetime form of ColdFusion security if the user's browser does not support cookies. In this case you do not use the cflogin tag, only the cfloginuser tag. It is the only time you should use the cfloginuser tag outside a cflogin tag.

Without browser cookies, the effect of the cfloginuser tag is limited to a single HTTP request. You must provide your own authentication mechanism and call cfloginuser on each page where you use ColdFusion login identification.

A basic authentication security scenario

An application that uses basic web server authentication might work as follows. The example in "Basic authentication user security example" implements this scenario.

1. When the user requests a page from a particular directory on the server for the first time after starting the browser, the web server displays a login page and logs the user in. The web server handles all user authentication.
2. Because the user requested a ColdFusion page, the web server hands the request to ColdFusion
3. When ColdFusion receives a request for a ColdFusion page, it runs the contents of the Application.cfm page before it runs the requested page. The Application.cfm page contains a cflogin tag. ColdFusion executes the cflogin tag body if the user is not logged into ColdFusion. The user is logged in if the cfloginuser tag has run successfully for this application and the user has not been logged out by a cflogout tag or the login has not timed out from inactivity.
4. Code in the cflogin tag body uses the user ID and password from browser login, contained in the cflogin.name and cflogin.password variables, as follows:
   1. First it checks the user's name against information it maintains about users and roles. In a simple case, the application might have two roles, one for users and one for administrators. The CFML assigns the Admin role to any user logged on with the user ID "Admin" and assigns the User role to all other users.
   2. The cflogin tag body code calls the cfloginuser tag with the user's ID, password, and roles to identify the user to ColdFusion.
5. Application.cfm completes processing and ColdFusion processes the requested application page.
6. The application pages use the IsUserInRole function to check whether the user belongs to a role before they run protected code that must be available only to users in that role. For example, administrative pages

   The application can use the GetAuthUser function to determine the user ID; for example, to display the ID for personalization. It can also use the ID as a database key to get user-specific data.

An application authentication security scenario

An application that does its own authentication might work as follows. The example in "Application-based user security example" implements this scenario.

1. Whenever ColdFusion receives a request for a ColdFusion page, it runs the contents of the Application.cfm page before it runs the requested page. The Application.cfm page contains a cflogin tag. ColdFusion executes the cflogin tag body if the user is not logged in. A user is logged in if the cfloginuser tag has run during the current session and the user had not been logged out by a cflogout tag.
2. Code in the cflogin tag body checks to see if it has received a user ID and password, normally from a login form.
3. If there is no user ID or password, the code in cflogin tag body displays a login form that asks for the user's ID and password.

   The form posts the login information back to the originally-requested page, and the login tag in Application.cfm runs again. This time, the cflogin tag body code checks the user name and password against a database, LDAP directory, or other policy store to ensure that the user is valid and get the user's roles.

4. If the user name and password are valid, the cflogin tag body code calls the cfloginuser tag with the user's ID and roles to identify the user to ColdFusion.
5. When the user is logged in, application pages use the IsUserInRole function to check whether the user belongs to a role before they run protected code that must be available only to users in that role.

   The application can use the GetAuthUser function to determine the user ID; for example, to display the ID for personalization. It can also use the ID as a database key to get user-specific data.

6. Each application page displays a link to a log-out form that uses the cflogout tag to log out the user. Typically, the logout link is in a page header that appears in all pages. The logout form can also be on the Application.cfm page.

Note:   A log-out option is not always required, as the user is automatically logged out when the browser closes or is inactive for the time-out period. However, you can enhance security in cases where a system might be shared by providing a log-out facility. You must explicitly log out a user before a new user can log in using the same browser session.

While this scenario shows one method for implementing user security, it is only an example. For example, your application could require users to log in for only some pages, such a pages in folder containing administrative functions. When you design your user security implementation, remember the following:

• Code in the cflogin tag body executes only if there is no user logged in.
• You must write the code that gets the identification from the user and tests this information against the a secure credential store.
• After you have authenticated the user, you use the cfloginuser to log the user into the ColdFusion session.

The following figure shows this flow of control. For simplicity, it omits the logout button.

Copyright © 2002, Macromedia Inc. All rights reserved.

Comments