Application development: Get details on the cflogin tag in ColdFusion MX

Through the <cflogin> tag, ColdFusion MX provides a mechanism for authenticating users of your Web application. See how this simple tag can speed up development time by creating reusable username and password methods.

User logins are used in almost every Web application. Macromedia is aware of this fact and to assist the developer they created <cflogin>. In their own words, <cflogin> is "a container for user login and authentication code." Take note that this is a "container" for code, not a preset section of code. For some reason, I was under the impression that <cflogin> was this magical little tool that would completely handle your user login and authentication code. Upon closer examination, I now realize that is not the case.

There are basically three parts to the container: the username, the password, and the roles. These are the basic requirements for user authentication: Who are you? (the username), How can I tell it's really you? (the password), and What are you allowed to do? (the role).

This built-in feature consists of three tags with their own attributes and two predefined functions. You still need to provide the overall logic for the user security and provide the look-up mechanism to check against. This is the area where my initial confusion was, because I thought it also provided the logic and look-up mechanism. I suppose that was wishful thinking, but as you'll see, filling in those missing parts isn't very complex after all.

The tags
The first tag is the <cflogin> tag. This is the framework for the entire container.
...your code goes here...

There are three attributes:
  • idletimeout—a timer to log-off inactive users
  • applicationtoken—which makes the logins application specific
  • cookiedomain—which associates the login with a particular domain

The next tag is the <cfloginuser> tag. This tag is required in your container code and is the basis for the container. It has three attributes: name stores a username, password stores a password, and roles stores a comma-delimited set of roles. You use this tag to associate these three attributes with the current user.

The last tag is the <cflogout> tag. This tag is optional and used only to forcefully flush out a user's data. Otherwise, the user's data gets dropped when the session ends. There are no attributes associated with this tag.

The functions & struct
There are two primary functions used in conjunction with the <cflogin> container. These functions are not actually used within the container, but they are meant to be used outside the container to access information set up within the container.

The first function is the GetAuthUser() function. This is used to figure out what value was set in the <cfloginuser> tag's name attribute. While it may be useful at times to display that value or manipulate it in some way, you're more likely to check if it's empty and take action accordingly. This will allow you a simple way to check that condition.

The second function is the IsUserInRole() function. This function takes a specific role value as a parameter. It takes the input role and compares it to the list setup in the <cfloginuser> roles attribute. If the passed-in role value is contained in the list, a true value is returned; otherwise, if it is not in the list, a false value is returned.

The cflogin struct contains two elements of name and password. This struct only exists within the container, and even then only if one of the following is true: A form is being submitted with input names of j_username and j_password, a CFHTTP Basic authentication request is made, or a Digest or NTLM authentication request is made.

The methodology
The most important thing to remember is that the code in the <cflogin> container only runs if the user is not logged in. Once the user is logged in, the code gets ignored. This is why the documentation says to put the container and code in the Application.cfm file. I wouldn't go that route, because I'm sure there are probably some pages in your site that don't need this security function, such as a "Sign-Up" page or a "Get more info" page.

What I would do instead is the same thing I've done in the past: I would put all my secured content in one particular directory. I tend to use a header file to control things such as which banner to show, which menu to display, which type of menu to use, etc. It is in this header file that I would include the login code, and only if calling a page in that secured directory.

For instance, say I have a set of "manager" tools available to the particular role of users. I put all the pages visible to the browser in a directory called "manager." I then set up my header file to accept a section attribute, telling me what section we're in. My code in the header file would look like the code in Listing A. Note: Read the code from top to bottom, paying particular attention to the comments (<!—- —->).

Quick and easy
As you can see, <cflogin> is a quick and easy way to secure your site with basic username/password authentication. For most simple to slightly complex projects, this methodology will work for you and can easily be reused. As you begin to head into more and more complex applications, you'll find yourself outgrowing the <cflogin> functionality. However, this does provide a nice springboard to start and learn from.

It's nice to see application vendors, such as Macromedia, take into account such commonplace elements as user authentication. Since this is a new feature added with CFMX 6.0, it's understandably simple. Whether Macromedia decides to further upgrade the container with other advanced features remains to be seen. Personally, I would like to see them continually add enhancements. With Macromedia's ability to convert complex procedures into simple tasks, they could turn this into a powerful reason for developers to switch over to the CFMX application framework.

Editor's Picks