Integrating OpenAuth into ColdFusion Applications

A common requirement we're faced with when developing a new application is authentication. Although it might not be the most exciting thing in the world to build, the necessity is clear. Thankfully the AOL Open Authentication (OpenAuth) API is an easy to use, flexible way to handle much of the plumbing required by this critical task (not to mention expose your application to millions of AOL users). This post will run through a quick tutorial on introducing the OpenAuth API to a ColdFusion application.

To get started, you'll obviously need an AOL developer account and ID. Unless you already have an AIM account, you'll need to surf to dev.aol.com and click Sign up now. Complete the form and you're there. Next you'll need to get a developer ID to use for the OpenAuth service which you may get at dev.aol.com/keys. Click Create a new devId, you should see a screen similar to Figure 1 below.

The information required to create a new dev id is self-explanatory. However take note that the Destination URL field is important for this application as this is the location users will be redirected upon successful authentication.

Developing the Application

Our task is to restrict access to a ColdFusion application which resides in a directory named openauth under the web root (see Listing 1 for the complete file structure).

   /
   +--- openauth
            +--- Application.cfm
            +--- index.cfm
            +--- index2.cfm

There are two files which are eligible for direct execution by the user, index.cfm and index2.cfm. Application.cfm is a special file which is executed ahead of the requested file. This behavior allows us to perform some basic checks on session state and configure the application's framework, the perfect situation to implement the OpenAuth API.

Listing 2 below shows the bulk of the code in Application.cfm which handles our authentication checks and calls to the OpenAuth service. The code starts off by enabling ColdFusion session management through the setting of client cookies, followed by the configuration of some session-level variables which are to used throughout the application, session.loggedIn and session.screenname. First a check is performed against the session.loggedIn variable. If false, the check is made on whether to get a status from the OpenAuth service or to redirect to the AOL login screen. The situation where the openAuthGetInfo user-defined function (see Listing 3) is invoked would be directly after the login succeeds. Once the status of OK is obtained from the service, our ColdFusion session.loggedIn variable is set to true. At this point, authentication against the AOL OpenAuth service is complete and we now maintain session state in ColdFusion.

<cfapplication name="openAuthDemo" sessionmanagement="yes" setclientcookies="yes">

<cfparam name="request.successURL" default="http://localhost:8501/openauth/" />
<cfparam name="request.aolDevId"   default="someAOLDevId" />
<cfparam name="session.loggedIn"   default="false" />
<cfparam name="session.screenname" default="" />

<cfif session.loggedIn eq "false">
	<!--- check for an access token --->
    <cfif isDefined( "url.token_a" )>
        <cfset st_getInfo = openAuthGetInfo( url.token_a ) />
        
        <!--- if the status comes back okay, preserve their status --->
        <cfif StructKeyExists( st_getInfo, "statusText" )>
        	<cfif st_getInfo.statusText eq "OK">
            	<cfset session.loggedIn   = "true" />
                <cfset session.screenname = st_getInfo.userData_loginId />
            <cfelse>
            	<cfset session.loggedIn   = "false" />
                <cfset session.screenname = "" />
            </cfif>
        </cfif>
    <cfelse>
        <!--- login --->
        <cfset loginURL = "http://api.screenname.aol.com/auth/login?f=qs" />
        <cfset loginURL = ListAppend( loginURL, "devId=#request.aolDevId#", "&" ) />
        <cfset loginURL = ListAppend( loginURL, "supportedIdType=SN,ICQ,OID", "&" ) />
        <cfset loginURL = ListAppend( loginURL, "succUrl=#urlEncodedFormat( request.successURL )#", "&" ) />
        <cflocation url="#loginURL#" />
    </cfif>
<cfelse>
	<cfoutput><em>#session.screenname#</em> is logged in.</cfoutput>
</cfif>

<cffunction name="openAuthGetInfo" output="yes" returntype="struct">
	<cfargument name="token" type="string" required="yes" />

	<cfset var local = StructNew() />
    <cfset local.st_info    = StructNew() />
    <!--- craft the 'getInfo' URL --->
    <cfset local.getInfoURL = "http://api.screenname.aol.com/auth/getInfo?f=qs" />
    <cfset local.getInfoURL = ListAppend( local.getInfoURL, "devId=#request.aolDevId#", "&" ) />
    <cfset local.getInfoURL = ListAppend( local.getInfoURL, "a=#urlEncodedFormat(arguments.token)#", "&" ) />
    <cfset local.getInfoURL = ListAppend( local.getInfoURL, "referer=#request.successURL#", "&" ) />
    
    <!--- call the getInfo method of the OpenAuth service --->
    <cfhttp url="#local.getInfoUrl#" method="get" />
    
    <!--- convert the name/value pairs returned to a ColdFusion structure --->
    <cfloop list="#cfhttp.FileContent#" index="i" delimiters="&">
    	<cfset StructInsert( local.st_info, ListFirst( i, "=" ), ListLast( i, "=" ) ) />
    </cfloop>

	<cfreturn local.st_info />
</cffunction>

The AOL Open Authentication API (OpenAuth) is a simple, powerful way of providing the critical task of authentication as well as offering your unique applications and services to the millions of existing AOL users. To learn more about OpenAuth, visit dev.aol.com/openauth.