Whatever message this page gives is out now! Go check it out!
Using ColdFusion security tags and functions
Last update:
May 18, 2026
ColdFusion provides the following tags and functions for user security:
Tag or function
Purpose
A container for user authentication and login code. The body of the tag runs only if the user is not logged in. When using application-based security, you place code in the body of the cflogin tag to check the user-provided ID and password against a data source, LDAP directory, or other repository of login identification. The body of the tag includes a cfloginuser tag (or a ColdFusion page that contains a cfloginuser tag) to establish the authenticated user's identity in ColdFusion.
Identifies (logs in) a user to ColdFusion. Specifies the user's ID, password, and roles. This tag is typically used inside a cflogin tag. 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.While the user is logged-in to ColdFusion, security functions access the user ID and role information.
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 as described in Logging out usersin Using ColdFusion security tags and functions.The cflogout tag does not take any attributes, and does not have a body.
Authenticates a user name and password against the NT domain on which ColdFusion server is running, and optionally retrieves the user's groups.
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.
Returns True if the current user is a member of the specified role.
Returns the ID of the currently logged-in user.This tag first checks for a login made with cfloginuser tag. If none exists, it checks for a web server login (cgi.remote_user.
Using the cflogin tag
The cflogin tag executes only if there is no currently logged-in user. It has the following three optional arguments that control the characteristics of a ColdFusion login:
Attribute
Use
idleTimeout
If no page requests occur during the idleTimeout period, ColdFusion logs out the user. The default is 1800 seconds (30 mins). This is ignored if login information is stored in the Session scope.
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
Specifies the domain of the cookie used to mark a user as logged-in. You use cookieDomain if you have a clustered environment (for example, x.acme.com, x2.acme.com, and so on). This lets the cookie work for all the computers in the cluster.
Login identification scope and the applicationToken attribute
The login identification created by the cflogin tag is valid only for pages within the directory that contains the page that uses 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 or Application.cfc unitization code. In normal use, you need not specify an applicationToken value in the cflogin tag.
Specifying the Internet domain
Use the cookieDomain attribute to specify the domain of the cookie used to mark a user as logged-in. You use cookieDomain if you have a clustered environment (for example, www.acme.com, www2.acme.com, and so on). This lets the cookie work for all computers in the cluster. For example, to ensure that the cookie works for all servers in the acme.com domain, specify cookieDomain=".acme.com". To specify a domain name, start the name with a period.
Note:
Before setting the cookie domain, consider the other applications or servers in the broader domain might have access to the cookie. For example, a clustered payroll application at payroll1.acme.com, payroll2.acme.com, and so on, might reveal sensitive information to the test computer at test.acme.com, if the cookie domain is broadly set to ".acme.com".
Getting the user ID and password
The cflogin tag has a built-in cflogin structure that contains two variables, cflogin .username and cflogin.password , if the page is executing in response to any of the following:
- Submission of a login form that contains input fields with the names j_username and j_password.
- A request that uses HTTP Basic authentication and, therefore, includes an Authorization header with the user name and password.
- A message from the Flash Remoting gatewayConnection object that has the setCredentials method set.
- A request that uses NTLM or Digest authentication. In this case, the user name and password are hashed using a one-way algorithm before they are placed in the Authorization header; ColdFusion gets the user name from the web server and sets the cflogin .password value to the empty string. You use the first three techniques with application authentication, and the last technique with web server authentication. The cflogin structure provides a consistent interface for determining the user's login ID and password, independent of the technique that you use for displaying the login form.
Note:
Login forms send the user name and password without encryption. Basic HTTP authentication sends the user name and password in a base64-encoded string with each request; this format can easily be converted back to plain text. Use these techniques only with https requests, or when you are not concerned about password security.
Provide login information to your application for authentication as follows:
Use a login form to get user information
When you build an application that gets the User ID and password using a login form, the cflogin tag checks for the existence of a cflogin structure containing the user's login information. If the structure does not exist, it displays a login form, typically using a cfinclude tag on a login page; the following code shows this use. In the Application.cfc onRequestStart method, or a ColdFusion page or CFC method called by the method, you have the following:
<cflogin>
<cfif NOT IsDefined("cflogin")>
<cfinclude template="loginform.cfm">
<cfabort>
<cfelse>
<!--- Code to authenticate the user based on the cflogin.user and
cflogin.password values goes here. --->
<!--- If User is authenticated, determine any roles and use a line like the
following to log in the user. --->
<cfloginuser name="#cflogin.name#"
Password = "#cflogin.password#"
roles="#loginQuery.Roles#">
</cfif>
</cflogin>A simple login form looks like the following:
<cfform name="loginform" action="#CGI.script_name#?#CGI.query_string#"
method="Post">
<table>
<tr>
<td>user name:</td>
<td><cfinput type="text" name="j_username" required="yes"
message="A user name is required"></td>
</tr>
<tr>
<td>password:</td>
<td><cfinput type="password" name="j_password" required="yes"
message="A password is required"></td>
</tr>
</table>
<br>
<input type="submit" value="Log In">
</cfform>Use a browser dialog box to get user information
Application authentication does not require you to use a login form; you can rely on the browser to display its standard login dialog box, instead. 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; that is, if it does not have a valid cflogin structure. The browser displays its login dialog box. When the user clicks the login button on the dialog box, the browser returns the login information as an HTTP Authorization header to ColdFusion, which places the information in the cflogin tag's cflogin structure. This technique has the advantage of simplicity; you do not need a login form and the user gets a familiar-looking login page. Be careful of security issues, however. The browser sends the user name and password in a base64-encoded string, not just when the user logs in, but with each request. Use SSL (Secure Sockets Layer) for all page transactions to protect the user ID and password from unauthorized access.
Note:
Ensure that your web server is configured correctly to support browser-based login forms for this use. For example, in IIS 5, enable anonymous access and disable Basic authentication and Integrated Windows authentication.
The following cflogin tag tells the browser to display a login form if the user has not logged in:
<cflogin>
<cfif NOT IsDefined("cflogin")>
<cfheader statuscode="401">
<cfheader name="www-Authenticate" value="Basic
realm=""MM Wizard #args.authtype# Authentication""">
</cfif>
<cfabort>
<cfelse>
<!--- code to authenticate the user based on the cflogin.user and
cflogin.password values goes here. --->
</cflogin>Log in a user using Flash Remoting
If you are developing a Rich Internet Application with Flash and Flash Remoting, your ColdFusion application does not need to be coded specially for a Flash login. The Flash Remoting gateway makes the user ID and password available to the cflogin tag in the cflogin structure. In your Flash code, you use the ActionScript SetCredentials method to send login information to ColdFusion. Your Flash SWF file displays the user ID and password fields, and uses their contents in the setCredentials method, as follows:
if (inited == null)
{
inited = true;
NetServices.setDefaultGatewayUrl("http://localhost/flashservices/gateway");
gatewayConnection = NetServices.createGatewayConnection();
gatewayConnection.setCredentials(userID, password);
myService = gatewayConnection.getService("securityTest.thecfc", this);
}For more information on using Flash Remoting, see Using the Flash Remoting Service_ and_ Using Flash Remoting Update.
Logging out users
After a user logs in, the ColdFusion user authorization and authentication information remains valid until any of the following happens:
- The application uses a cflogout tag to log out the user, usually in response to the user clicking a log-out link or button.
- If your application uses the Session scope for login information, the session ends.
- If your application does not use the Session scope for login information, the user does not request a new page for the cflogin tag idleTimeout period.
- If your application does not use Session scope for login information, or if you use J2EE-based session identification, the user closes all browser windows. Logging out a user by using the cflogout tag does not close the user's session, but if you use session login storage, it does remove the login information (the Session.cfauthorization variable) from the Session scope. For more information on ending sessions, see Ending a session in Configuring and using session variables.
Note:
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 can access pages with the first user's login.
We're glad. Tell us how this page helped.
We're sorry. Can you tell us what didn't work for you?
Share additional feedback to help us improve.
0/255
|
