Some Thoughts On Handling 401 Unauthorized Errors With jQuery

As I continue to make the journey from the "traditional" request-response web application design to thick-client, AJAX-driven, realtime applications, I am always finding new problems to solve. Yesterday, on a project, we started seeing an issue where a user would have two tabs open for the same app; then, they would explicitly log-out of one tab which would cause all of the AJAX requests in the other tab to break (they were being diverted to the login page). To fix this in the quickest, easiest way possible, we set up a global AJAX handler that would listen for 401 Status Codes and redirect the user to the login page.

The first part of our problem was that our login page was not returning a 401 status code. This didn't matter for AJAX requests that were expecting JSON responses (as they would fail anyway); the problem really become obvious with AJAX requests that were expecting HTML responses. To these requests, the Login HTML was just as good as the Modal Window HTML.

By adding a 401 status code to the login page, at least we could start to get all AJAX requests to fail across the board (both those expecting JSON and HTML return data).

Once we got the AJAX requests to start failing, we had to figure out a way to forward the user to the login page once an asynchronous 401 status code was returned. This particular project has a whole mess of AJAX functionality; so, we didn't want to go through and retrofit each request/response interaction. Instead, we configured a global AJAX handler that listened specifically for the 401 status code; and, if it was triggered, it would use JavaScript to forward the user to the Login page.

To demonstrate this, I put together an extremely simple application that maintains session and has one AJAX request. If you watch the video above, you can see this in action; but, let's step through the code.

I'm gonna start with the main index page as this is really the only thing worth while - the other pages are just there to support logged-in/logged-out status.

Index.cfm - The "Application" Interface

As you can see, we have one AJAX method - getNextMessage() - that runs on a 5-second interval, requesting messages from the server. Typically, these message requests come back with a 200 OK response and the page is updated accordingly. If, however, the user becomes logged-out, these AJAX requests will start coming back with a 401 Unauthorized response.

To handle this 401 status code, we are using the $.ajaxSetup() function to define a default 401 status code handler. This handler will be merged into all AJAX requests within the entire application (assuming they don't override it) and will therefore be triggered when any AJAX request comes back with a 401 status code.

NOTE: Status Code callbacks and "error" callbacks co-exist. This means that a 401 status code callback will not prevent an error callback from being used - and vice-versa. Should a 401 error come back, both the error handler and the 401 callback will be invoked.

I don't know if this is the right way to do things; this is just the first idea that we came up with when we started to see this multi-tab issue arise. And, it seems to have solved the problem reasonably well.

Now that you see how the main, AJAX-driven part of the application is working, let's quickly run through the support files.

Application.cfc - The ColdFusion Application Framework

The Application.cfc just defines the application settings and manages the incoming requests. As you can see above, the user's session has a simple logged-in flag. If the user is logged-in, they can request any script; if they are logged-out, all requests ultimately execute the login page.

The login page then provides hooks to both log into and out of the system:

Login.cfm

As you can see, this page simply provides a way to toggle the logged-in status of the user for testing purposes. One of the most critical aspects of this page, however, is the fact that the login page returns a 401 Unauthorized status code. It's this status code that allows the AJAX requests to invoke the proper success and error callbacks.

I could probably have returned the 401 status code all the time; but, for a little added elegance, I am only returning the 401 status code if the user requests a page that is not the login page. So, if they access the login page directly, there is no authorization required.

And, or course, we had our message AJAX request that simply returned a string:

Message.cfm - Our AJAX Target Page

Pretty much nothing going on there.

Again, I don't know if this is the best way to handle authorization in an AJAX-driven application; but, by making judicious use of the 401 status code and by defining a global 401 AJAX response handler, we were able to fix our problem in just a matter of minutes. Every day, I find a new reason to love jQuery even more!

You Might Also Be Interested In: