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 put 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.

The following sections describe how you provide login information to your application for authentication

Using 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">
    </cfif>
     <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#">
</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>

Using 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 puts 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. You must 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.

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>

Logging 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.