ColdFusion MX : Implementing user security

The following section provide several examples of ways to implement security using basic authentication and application authentication

Basic authentication user security example

The example in this section shows how you might implement user security using web-server basic authentication and two roles, user and administrator.

You can test the security behavior by adding your own pages to the same directory as the Application.cfm page.

Example: Application.cfm

Reviewing the code

The following table describes the CFML code in Application.cfm and its function:


Code	Description
<cfapplication name="Orders"	Identifies the application. The login information on this page only applies to this application.
<cflogin> <cfif IsDefined( "cflogin" )> <cfif cflogin.name eq "admin"> <cfset roles = "user,admin"> <cfelse> <cfset roles = "user"> </cfif>	Executes if there is no logged-in user. Makes sure the user is correctly logged in by the web-server. (Otherwise there would be no `cflogin` variable.) Sets a roles variable based on the user's ID. assigns users named "admin" to the admin role. Assigns all other users to the users role.
<cfloginuser name = "#cflogin.name#" password = "#cflogin.password#" roles = "#roles#" />	Logs the user into the ColdFusion security system and specifies the user's password, name and roles. Gets the password and name directly from the `cflogin` structure.
<cfelse> <!--- this should never happen ---> <h4>Authentication data is missing.</h4> Try to reload the page or contact the site administrator. <cfabort>	This code should never run, but if the user somehow got to this page without logging in to the web server, this message would display and ColdFusion would stop processing the request.
</cfif> </cflogin>	Ends if/else block. Ends the cflogin tag body.

Example: securitytest.cfm

The securitytest.cfm page shows how any application page can use ColdFusion user authorization features. The web server ensures the existence of an authenticated user, and the Application.cfm page ensures that the user is assigned to roles the page content appears. The securitytest.cfm page uses the IsUserInRole and GetAuthUser functions to control the information that is displayed.

Reviewing the code

The following table describes the securitytest.cfm page CFML code and its function:


Code	Description
<cfoutput> <h2>Welcome #GetAuthUser()#!</h2> </cfoutput>	Displays a welcome message that includes the user's login ID.
ALL Logged-in Users see this message.<br> <br>	Displays this message in all cases. The page does not display until a user is logged in.
<cfscript> if (IsUserInRole("admin")) WriteOutput("users in the admin role see this message.<br><br>"); if (IsUserInRole("user")) WriteOutput("Everyone in the user role sees this message.<br><br>"); </cfscript>	Tests whether the user belongs to each of the valid roles. If the user is in a role, displays a message with the role name. The user sees one message per role to which he or she belongs.

Application-based user security example

The example in this section shows how you might implement user security by authenticating users and then allowing users to see or use only the resources that they are authorized to access.

You can test the security behavior by adding your own pages to the same directory as the Application.cfm page.

The example gets user information from the LoginInfo table of the CompanyInfo database that is installed with ColdFusion. You can replace this database with any database containing UserID, Password, and Roles fields. The sample database contains the following data:


UserID	Password	Roles
BobZ	Ads10	Employee,Sales
JaniceF	Qwer12	Contractor,Documentation
RandalQ	ImMe	Employee,Human Resources,Manager

Because spaces are meaningful in roles strings, you should not follow the comma separators in the Roles fields with spaces.

Example: Application.cfm

Reviewing the code

The Application.cfm page executes before the code in each ColdFusion page in an application. For more information on the Application.cfm page and when it is executed, see Chapter 13, "Designing and Optimizing a ColdFusion Application". The following table describes the CFML code in Application.cfm and its function:.


Code	Description
<cfapplication name="Orders" sessionmanagement="Yes">	Identifies the application and enables Session scope variables.
<cfif IsDefined("Form.logout")> <cflogout> </cfif>	If the user just submitted the logout form, logs out the user. The following `cflogin` tag runs as a result.
<cflogin> <cfif NOT IsDefined("cflogin")> <cfinclude template="loginform.cfm"> <cfabort>	Executes if there is no logged-in user. Tests to see if the user has submitted a login form. If not, uses `cfinclude` to display the form. Uses the built-in cflogin variable that contains the user name and password if it was submitted by the login form. The `cfabort` tag prevents processing of any code that follows on this page.
<cfelse> <cfif cflogin.name IS "" OR cflogin.password IS ""> <cfoutput> <H2>You must enter text in both the User Name and Password fields</H2> </cfoutput> <cfinclude template="loginform.cfm"> <cfabort>	Executes if the user submitted a login form. Tests to make sure both name and password have data. If either variable is empty, displays a message, followed by the login form. The `cfabort` tag prevents processing of any code that follows on this page.
<cfelse> <cfquery name="loginQuery" dataSource="CompanyInfo"> SELECT UserID, Roles FROM LoginInfo WHERE UserID = '#cflogin.name#' AND Password = '#cflogin.password#' </cfquery>	Executes if the user submitted a login form and both fields contain data. Uses the `cflogin` structure's `name` and `password` entries to find the user record in the database and get the user's roles.
<cfif loginQuery.Roles NEQ ""> <cfloginuser name="#cflogin.name#" Password = "#cflogin.password#" roles="#loginQuery.Roles#">	If the query returns data in the Roles field, logs in the user using the UserID and Roles fields from the database. In this application, every user must be in some role.
<cfelse> <cfoutput> <H2>Your login information is not valid.<br> Please Try again</H2> </cfoutput> <cfinclude template="loginform.cfm"> <cfabort>	Executes if the query did not return a role. If the database is valid, this means there was no entry matching the user ID and password. Displays a message, followed by the login form. The `cfabort` tag prevents processing of any code that follows on this page.
</cfif> </cfif> </cfif> </cflogin>	Ends loginquery.Roles test code. Ends form entry empty value test. Ends form entry existence test. Ends `cflogin` tag body.
<cfif GetAuthUser() NEQ ""> <cfoutput> <form action=MyApp/index.cfm" method="Post"> <input type="submit" Name="Logout" value="Logout"> </form> </cfoutput> </cfif>	If a user is logged in, displays the Logout button. If the user clicks the button, posts the form to the application's (theoretical) entry page, index.cfm. Application.cfm then logs out the user and displays the login form. If the user logs in again, ColdFusion displays index.cfm.

Example: loginform.cfm

Reviewing the code

The following table describes the loginform.cfm page CFML code and its function:


Code	Description
<cfset url="http://" & "#CGI.server_name#" & ":" & "#CGI.server_port#" & "#CGI.script_name#"> <cfif CGI.query_string IS NOT ""> <cfset url=url & "?#CGI.query_string#"> </cfif>	Constructs the URL to use in the form's `action` attribute from CGI variables. The CGI.script_name variable identifies the originally requested page, because that page's invocation of Application.cfm causes the login form to be displayed. Appends any URL query string used in requesting the page so the page can process the request. A more secure application would use the HTTPS protocol to encrypt the user name and password. To use HTTPS, you must obtain a security certificate and enable the protocol in your web server.
<H2>Please Log In</H2> <cfoutput> <form action="#url#" method="Post"> <table> <tr> <td>username:</td> <td><input type="text" name="j_username"></td> </tr> <tr> <td>password:</td> <td><input type="password" name="j_password"></td> </tr> </table> <br> <input type="submit" value="Login"> </form> </cfoutput>	Displays the login form. The form requests a user ID and password and posts the user's input to the page specified by the url variable. Uses the field names j_username and j_password. ColdFusion automatically puts form fields with these values in the `cflogin.name` and `cflogin.password` variables inside the `cflogin` tag.

Example: securitytest.cfm

The securitytest.cfm page shows how any application page can use ColdFusion user authorization features. Application.cfm ensures the existence of an authenticated user before the page content appears. The securitytest.cfm page uses the IsUserInRole and GetAuthUser functions to control the information that is displayed.

Reviewing the code

The following table describes the securitytest.cfm page CFML code and its function:

Code

Description

<cfoutput>
<h2>Welcome #GetAuthUser()#!</h2>
</cfoutput>

Displays a welcome message that includes the user's login ID.

ALL Logged-in Users see this 	message.<br>
<br>

Displays this message in all cases. The page does not display until a user is logged in.

<cfscript>
	if (IsUserInRole("Human Resources"))
		WriteOutput("Human Resources members
		see this message.<br><br>");
	if (IsUserInRole("Documentation"))
		WriteOutput("Documentation members see
		this message.<br><br>");
	if (IsUserInRole("Sales"))
		WriteOutput("Sales members see this
		message.<br><br>");
	if (IsUserInRole("Manager"))
		WriteOutput("Managers see this
		message.<br><br>");
	if (IsUserInRole("Employee"))
		WriteOutput("Employees see this
		message.<br><br>");
	if (IsUserInRole("Contractor"))
		WriteOutput("Contractors see this
		message.<br><br>");
</cfscript>

Tests whether the user belongs to each of the valid roles. If the user is in a role, displays a message with the role name.

The user sees one message per role to which he or she belongs.

Using application-based security with a browser's login dialog

You do not have to create a login page to display a user login form; you can rely on the browser to display its standard login page. To do so, your cflogin tag body returns an HTTP status 401 to the browser if the user is not logged in or if the login fails. The browser then displays its login page and returns the information to the cflogin tag's cflogin structure when the user clicks the login button.

For example, the following code tells the browser to display a login form if the user has not logged in, or if the user does not provide a name "user" and password "p1", or a name "admin" and password "p2":

Using an LDAP Directory for security information

LDAP directories are often used to store security information. The following example cflogin tag checks an LDAP directory to authenticate the user and retrieve the users roles.

The most important thing to note in this example is that it queries the directory twice, first as the directory manager, then with the user's identity:

The "Reviewing the code" section that follows describes the code's function in detail. For more information on using LDAP directories with ColdFusion, see Chapter 23, "Managing LDAP Directories".

Reviewing the code

The following table describes the code and its function:


Code	Description
<cflogin> <cfset root = "o=macromedia.com"> <cfset server="ldap.macromedia.com"> <cfset port="389"> <cfset filter = "(&(objectclass=*) (uid=#Form.UserID#))"> <cfset LDAP_username = "cn=directory manager"> <cfset LDAP_password = "password">	Starts `cflogin` tag body. Sets several of the values used as attributes in the `cfldap` tags as variables. This ensures that the same value is used in both tags, and makes it easier to change the settings if needed. Sets the directory manager's user name and password for the first query.
<cftry> <cfldap action="QUERY" name="userSearch" attributes="uid,dn" start="#root#" scope="SUBTREE" server="#server#" port="#port#" filter="#filter#" username="#LDAP_username#" password="#LDAP_password#" >	In a cftry block, uses the directory manager's identity to get the distinguished name (dn) for the user. If the user ID is not in the directory, returns an empty record set.
<cfcatch type="Any"> <cfset UserSearchFailed = true> </cfcatch> </cftry>	Catches any exception. Sets a UserSearchFailed flag to True. Ends the `cftry` block.
<cfif NOT userSearch.recordcount OR UserSearchFailed> <cfoutput> <script> alert("UID for #uid# not found"); </script> </cfoutput> <cfabort> </cfif>	If the LDAP lookup did not return any results or the UserSearchFailed flag is True, displays an error message and ends processing of the page
<cftry> <cfldap action="QUERY" name="auth" attributes="dn,roles" start="#root#" scope="SUBTREE" server="#server#" port="#port#" filter="#filter#" username="#userSearch.dn#" password="#Form.password#">	In a try block, uses the distinguished name from the previous query and the user-supplied password to access the directory and get the user's roles. If either the dn or password is invalid, the `cfldap` tag throws an error, which is caught in the `cfcatch` block.
<cfcatch type="any"> <cfif FindNoCase("Invalid credentials", cfcatch.detail)> <cfoutput><script>alert("User ID or Password invalid for user: #Form.userID#")</script> </cfoutput> <cfabort> <cfelse> <cfoutput><script>alert("Unknown error for user: #Form.userID# #cfcatch.detail#") </script></cfoutput> <cfabort> </cfif> </cfcatch> </cftry>	Catches any exceptions. Tests to see if the error information includes the string "invalid credentials", which indicates that either the dn or password is invalid. If so, displays an error message indicating the problem. Otherwise, displays a general error message. If an error is caught, the `cfabort` tag ends processing of the request after displaying the error description.
<cfif auth.recordcount> <cfloginuser name="#Form.userID#" password="#Form.password#" roles="#auth.roles#"> </cfif> </cflogin>	If the second query returned a valid record, logs in the user and sets the roles to the values returned by the query. Ends the `cflogin` tag body.

Comments are no longer accepted for ColdFusion MX. ColdFusion 8 is the current version.

Comments

cfmxdave said on May 13, 2002 at 1:14 PM :

In the section ?Application-based user security example? there is a code example for loginform.cfm.
The first line creates a variable called url that is used as the action page for the form. I found that this throws an error when the page gets to the form declaration. The error says something about this being a complex variable when it should be a simple variable. I was able to remedy the situation by changing the variable name ?url? to ?newurl? (or anything else for that matter) in all instances.

cfmxdave said on May 13, 2002 at 1:32 PM :

In the following code (used in a couple of places)
<cfif GetAuthUser() NEQ "">
<cfoutput>
<form action=MyApp/index.cfm" method="Post">
<input type="submit" Name="Logout" value="Logout">
</form>
</cfoutput>
</cfif>
there is a double quote missing from the front of MyApp/index.cfm"

sgilson102 said on Jun 24, 2002 at 5:20 PM :

Here is how I solved that error...

<cfset URLTMP="http://" &"#CGI.Server_name#" & ":" & "#cgi.SERVER_PORT#" & "#CGI.Script_name#">
<cfif CGI.QUERY_STRING is not "">
<CFset URLFIN=URLTMP & "?#CGI.QUERY_STRING#">
<cfelse>
<CFset URLFIN=URLTMP>
</cfif>
<H2>Please Log In</H2>
<cfoutput>
<form action="#urlfin#" method="Post">

rnielsen said on Sep 10, 2002 at 8:09 PM :

URL is a reserved word. I have entered this as doc bug number 47944.

carehart@systemanage said on Sep 14, 2002 at 8:38 PM :

This page's "Application-based user security example" must be changed to clarify that the "cflogin" scope will exist <b>**only**</b> if the form being used for the login uses j_username and j_password for the input fields.

If the user doesn't notice this and just uses "username" and "password" on their own (rather than cutting and pasting the form offered in the code later in the page), they'll find that the code doesn't work at all--because the first test for isdefined("cflogin") is never true.

This isn't at all obvious.

jochemd said on Oct 21, 2002 at 8:31 PM :

If you have a problem with CF MX caching login information upon logout, try moving the cflogout tag below the cflogin tag.

carehart@systemanage said on Nov 29, 2002 at 11:06 PM :

Regarding the feature described in the section "Using application-based security with a browser's login dialog", of using using the status code 401 access denied approach to authentication, I (and others) have found that it fails with web server integration using IIS. It does work against the built-in web server. I've found no other references to this in the forums, the knowledge base, nor these livedocs comments.

When run under IIS, you can never authenticate (using the sample admin/p1 combination for username/password that's offered in the code example).

This is really annoying, if for no other reason that the docs don't say it shouldn't work. Has anyone else experienced or explored this?

carehart@systemanage said on Nov 29, 2002 at 11:11 PM :

More on that statuscode 401 approach to authentication, I found something interesting in Chapter 11 that may be useful for readers to note. (It's not related at all to the issue I just brought up about it failing on IIS.)

Chapter 11 has this statement about how the "realm" feature of this approach can be used which ought to be present on this page as well:

"The security realm name can be used to bind multiple directories together. If Application.cfm files located in those directories use the same realm name, only a single login is required to access resources in those directories. However, each Application.cfm file can establish different roles for a user. "

If it does indeed work, that's cool to know (and a potential explanation for when people find that use of the approach in one directory causes users to login without an authentication prompt in another directory.)

/charlie

carehart@systemanage said on Dec 5, 2002 at 4:09 AM :

Tom, that fix does not solve the problem I raised, which is that the example of find statuscode 401 authentication (code above on this page) simply fails to work if IIS integration is implemented. It works find on the built-in web server.

I don't know if you were referring to that problem in your note above, but changing the authentication settings for the directory in IIS made no difference to the code. My testing has shown that CF is simply not setting the CFLOGIN scope if the user is coming in through IIS.

This is on both the base version and the updater 1.

tommuck said on Nov 30, 2002 at 10:29 PM :

The problem is in the default IIS settings. To get the cflogin tags to work properly -- allowing the setCredentials() method to work in Flash Remoting -- you need to open up IIS admin interface and right-click on your Web application and choose Properties > Directory Security > Anonymous Access > Edit. Here you will have to uncheck the Integrated Windows Authentication. Using integrated authentication only allows users that are set up under Windows to access pages in a directory protected by a cflogin system. The system works perfectly with the built-in CFMX web server. Screenshot of the admin interface of IIS at http://www.flash-remoting.com/notablog/images/iis_auth.jpg

Slam said on May 10, 2003 at 8:13 AM :

wow i looked all over the place wondering what i was doing wrong with my app and here i find out its IIS ... bah .. im glad i finally found the info .. but you should SAY THAT ....

Doug Cain said on Dec 8, 2003 at 7:24 PM :

I noticed my application wasn't logging out after the idletimeout which I thought was weird as I based my code on the MM cflogin example. Found this in the forums which solves it and explains the problem:

http://webforums.macromedia.com/coldfusion/messageview.cfm?catid=12&threadid=647844&highlight_key=y&keyword1=cflogin

Seems like the <cfif NOT IsDefined("cflogin")> breaks the idletimeout state for some reason (bug?)

Anyway thought this would be helpful for anyone who is looking at cflogin.

No screen name said on Jul 9, 2004 at 12:04 PM :

I had to do this to make the idleTimeout work properly...

<cfapplication name="EXAMPLE" loginStorage="session" sessionmanagement="Yes" setclientcookies="Yes">


<cfif isDefined("session.cfauthorization")>
<cfset cookie.CFAUTHORIZATION_EXAMPLE=session.CFAUTHORIZATION>
</cfif>

Current page: http://livedocs.adobe.com/coldfusion/6/Developing_ColdFusion_MX_Applications_with_CFML/appSecurity5.htm

Developing ColdFusion MX Applications with CFML
Securing Applications