# Example of User Authentication and Authorization

The following sample pages illustrate how a developer might implement user security by authenticating users and then allowing users to see/use only the resources they are authorized to use.

In this example, a user requests a page in an application named Orders, which is part of a security context, also named Orders, that governs pages and resources for an order tracking application.

User security is generally handled in two steps:

- First, the `Application.cfm` page checks to see if the current user is authenticated. If not, we present a login form and the user must submit a username and password for authentication.

  If a user passes the authentication test, ColdFusion passes a cookie to carry the user's authentication state to subsequent application pages governed by this `Application.cfm` page.

- Next, only authenticated users are able to access the requested application page, for selecting and updating customer orders in a database. This page checks to see which resources the authenticated user is authorized to see and use.

## Authenticating users in Application.cfm

This example code for an `Application.cfm` page checks first to see whether the current user is authenticated by checking to see if a login form was submitted. If the username and password can be authenticated for the current security context, the user passes through and the requested page is served.

If the `Application.cfm` page does not receive the user's login information from the previous page, it prompts the user to provide a username and password. The user's response is checked against the list of valid users defined for the current security context.

If the user passes the authentication step too, the requested page appears. We use the CGI variables script_name and query_string keep track of the page originally requested. This way, once users are authenticated, we can serve the page they originally requested.

All pages governed by this `Application.cfm` page -- those in the same directory as `Application.cfm` and in its sub-tree -- will invoke this authentication test.

Note | To use this code in your own `Application.cfm` page, change the application name and security context name to match your application and security names.

### Example: Application.cfm

    <CFAPPLICATION NAME="Orders">

    <CFIF not IsAuthenticated()>
        <!--- The user is not authenticated --->

        <CFSET showLogin = "No">
    <CFIF IsDefined("form.username") and
        IsDefined("form.password")>

    <!--- The login form was submitted --->
    <CFTRY>
        <CFAUTHENTICATE SecurityContext="Orders"
            username="#form.username#"
            password="#form.password#"
            setCookie="YES">

    <CFCATCH TYPE="security">
    <!--- Security error in login occurred,
        show login again --->
        <H3>Invalid Login</H3>
        <CFSET showLogin = "Yes">
    </CFCATCH>
    </CFTRY>

    <CFELSE>
    <!--- The login was not detected --->
        <CFSET showLogin = "Yes">
    </CFIF>

    <CFIF showLogin>
    <!--- Recreate the url used to call this template --->
        <CFSET url = "#cgi.script_name#">
    <CFIF cgi.query_string is not "">
        <CFSET url = url & "?#cgi.query_string#">
    </CFIF>

    <!--- Populate the login with the recreated url --->

    <CFOUTPUT>
        <FORM ACTION="#url#" METHOD="Post">
        <TABLE>
        <TR>
        <TD>username:</TD>
        <TD><INPUT TYPE="text" NAME="username"></TD>
        </TR>

        <TR>
        <TD>password:</TD>
        <TD><INPUT TYPE="password" NAME="password"></TD>
        </TR>
        </TABLE>
        <INPUT TYPE="submit" VALUE="Login">

        </FORM>
    </CFOUTPUT>
    <CFABORT>
    </CFIF>

    </CFIF>

## Checking for authentication and authorization

Inside application pages, developers can use the IsAuthorized function to check whether an authenticated user is authorized to access the protected resources, and then display only the authorized resources.

The following sample page appears to users who pass the authentication test in the `Application.cfm` page above. It uses the IsAuthorized function to test whether authenticated users are allowed to update or select data from a datasource.

### Example: orders.cfm

    <!---  This example calls the IsAuthorized function. --->

    ...

    <!--- First, check whether a form button was submitted --->

    <CFIF IsDefined("form.btnUpdate")>

    <!--- Is user is authorized to update or select
        information from the Orders data source? --->

        <CFIF ISAUTHORIZED("DataSource", "Orders", "update")>
        <CFQUERY NAME="AddItem" DATASOURCE="Orders">
            INSERT INTO Orders
            (Customer, OrderID)
            VALUES
                <CFOUTPUT>(#Customer#, #OrderID#)</CFOUTPUT>
            </CFQUERY>
            <CFOUTPUT QUERY="AddItem">
            Authorization Succeeded. Order information added:
            #Customer# - #OrderID#<BR>
            </CFOUTPUT>

        <CFELSE>
            <CFABORT SHOWERROR="You are not allowed
            to update order information.">

        </CFIF>

    </CFIF>

    <CFIF ISAUTHORIZED("DataSource", "Orders", "select")>
        <CFQUERY NAME="GetList" DATASOURCE="Orders">
            SELECT *    FROM Orders
        </CFQUERY>
        Authorization Succeeded. Order information follows:
        <CFOUTPUT QUERY="GetList">
            #Customer# - #BalanceDue#<BR>
        </CFOUTPUT>

    <CFELSE>
        <CFABORT SHOWERROR="You cannot view
            order information.">

    </CFIF>