ColdFusion 10 - WebSocket Authentication And The onWSAuthenticate() Event Handler

As we saw yesterday, neither session cookies nor session scope are available during a ColdFusion 10 WebSocket request. Authentication and state management have to take place directly inside of the WebSocket control flow. To enable this, ColdFusion 10 has provided the client-side authenticate() method and the server-side event handler, onWSAuthenticate(). ColdFusion 10 also allows for single-sign-on; however, this requires the use of CFLogin - something with which I have very little experience.

NOTE: At the time of this writing, ColdFusion 10 was in public beta.

Most of the ColdFusion 10 WebSocket events are handled on the server using a Channel Listener. In the following demo (and in my previous demos), I use the ColdFusion component, WSApplication.cfc, as my channel listener. This listener pipes incoming requests into custom event handlers that I have defined in my Application.cfc. The WebSocket authentication event is not specific to any particular channel - it is only specific to a given client. As such, WebSocket authentication does not require a channel listener; it takes place directly in the Application.cfc ColdFusion framework component using the event handler, onWSAuthenticate().

When onWSAuthenticate() is invoked, you are provided with a username, a password, and a user object. This user object will be available for every WebSocket request made by the associated client. As such, any changes that you make to the user object within the onWSAuthenticate() event handler will be available in any subsequent requests made by the same client.

There's nothing magical about WebSocket authentication. Just as with your typical user authentication, we're simply setting flags in one request and then checking for those flags on subsequent requests. There's nothing more to it than that - ColdFusion isn't doing anything implicitly with your authentication code other than using the return() value as a means to trigger a success or error response on the client.

To demonstrate WebSocket authentication, I've created a simple demo that denies Publish events until the user has authenticated. While I don't use a database for this request, you can see that my onWSAuthenticate() event handler looks up the user credentials in a server-side cache. Upon authentication, a userID property is stored in the user's connection info - this userID is then available for all subsequent requests from the same client.

Application.cfc - Our ColdFusion Application Framework Component

As you can see, once the onWSAuthenticate() event handler is invoked, the property, userID, is available in the subsequent onWSRequestStart() event handler. I can then use the existence of this property to determine if the WebSocket client has been authenticated. ColdFusion 10 provides the flag, "authenticated", as part of the persistent connection object. You can set this in the onWSAuthenticate() event handler if you want to and then use it in subsequent WebSocket events; but, like I said before, ColdFusion doesn't do anything implicitly with this value - managing requests is left up to your discretion.

To make use of this authentication code, I've set up a simple client-side demo that can publish a static message with and without authentication. In each case, the request and response is logged to the console.

index.cfm - Our Client-Side User Interface (UI)

Again, I am using RequireJS as the dependency manager for this ColdFusion 10 WebSocket example. This way, I can use my AMD-compliant ColdFusion 10 WebSocket module. For this demo, I have updated ColdFusionWebSocket() module to return a Deferred object from the authenticate() method. The underlying WebSocket uses success and error events to manage authentication; but, since authentication felt very much like a request/response relationship, I thought the most useful approach would be to provide the Promise of a result on which you could directly bind resolve and reject event handlers.

As you will see in the following code, the Deferred-based authentication provides a very natural, intuitive approach to authentication.

main.js - Our Client-Side Controller And Application Bootstrap

As you can see in the above code, my ColdFusionWebSocket() module provides an authenticate() method. This method returns a Deferred promise on which you can bind success and fail event handlers. In this case, I'm simply logging those events out to the console.

As I'm making WebSocket requests from the client to the server, the Application.cfc ColdFusion framework component is logging information to the log file. You can see this in the video; it demonstrates how the authentication information is persisted on the server-side across client requests.

ColdFusion 10 WebSockets have their own session management. This exists outside of the normal ColdFusion session management; but, it works in almost the same way - we have a persistent, server-side object associated with a given client. This object can then be mutated over time. The onWSAuthenticate() event handler gives us an easy way to work authentication into the management of that session object. And, hopefully, my ColdFusionWebSocket() module makes this easier as well.

You Might Also Be Interested In: