The following sections provide two detailed security scenarios. The first scenario uses the web server to perform the authentication against its user and password database. The second scenario uses ColdFusion for all authentication and authorization.
A web server authentication security scenario
An application that uses web server authentication might work as follows. The example in Web server-based authentication user security example implements this scenario.
- 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 in the user. The web server handles all user authentication.
- Because the user requested a ColdFusion page, the web server hands the request to ColdFusion.
- When ColdFusion receives a request for a ColdFusion page, it instantiates the Application.cfc and runs onRequestStart method. If you use an Application.cfm page in place of the Application.cfc, it runs the contents of the Application.cfm page before it runs the requested page. The onRequestStart method or 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.
- Code in the cflogin tag body uses the user ID and password from the browser login, contained in the cflogin.name and cflogin.password variables, as follows. (With Digest or NTLM web server authentication, the cflogin.password variable is the empty string.)
- 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.
- It calls the cfloginuser tag with the user's ID, password, and roles, to identify the user to ColdFusion.
- Application.cfc or the Application.cfm page completes processing, and ColdFusion processes the requested application page.
- The application uses the IsUserInAnyRole function to check whether the user belongs to a role before it runs 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.
Important: If you use web server-based authentication or any form authentication that uses a Basic HTTP Authorization header, the browser continues to send the authentication information to your application until the user closes the browser, or in some cases, all open browser windows. As a result, after the user logs out and your application uses the cflogout tag, until the browser closes, the cflogin structure in the cflogin tag will contain the logged-out user's UserID and password. If a user logs out and does not close the browser, another user might access pages with the first user's login.
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.
- Whenever ColdFusion receives a request for a ColdFusion page, it instantiates the Application.cfc and runs the onRequestStart method. If you use an Application.cfm page in place of Application.cfc, ColdFusion runs the contents of the Application.cfm page before it runs the requested page. The onRequestStart method or Application.cfm page contains the 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.
- Code in the cflogin tag body checks to see if it has received a user ID and password, normally from a login form.
- If there is no user ID or password, the code in the 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 cflogin tag in the onRequestStart method or the Application.cfm page 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.
- If the user name and password are valid, the cflogin tag body code calls the cfloginuser tag with the user's ID, password, and roles, to identify the user to ColdFusion.
- When the user is logged in, application pages use the IsUserInAnyRole 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.
- Each application page displays a link to a logout 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 in the Application.cfc (for example, in the onRequestStart or onRequestEnd method) or on the Application.cfm page.
Although 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 as pages in a folder that contains 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.
- With application authentication, you write the code that gets the identification from the user and tests this information against a secure credential store.
- After you have authenticated the user, you use the cfloginuser tag to log the user into ColdFusion.
The following image shows this flow of control. For simplicity, it omits the log-out option.