Back in January I showed how you can add a "flyout" login box to any page of your Domino application. It's a nice easy way for users to login at any point they wish to. The one problem with it is that if, for whatever reason, authentication fails, you are then redirected to the normal login form --  be it the ugly default one or a custom version from domcfg.nsf.

Whichever login form the user ends up seeing and no matter if it's ugly or not the chances are you didn't ever want the user to leave the application itself in the first place. Particularly if the interface happens to be Ext-based.

My latest task has been to implement a login interface for just such an Ext-based Domino application. In order to avoid the user seeing anything other than a pretty-looking Ext app I decided to use Ajax requests to log the user in. It turns out that what I thought would be a relatively simple exercise took quite a while. What I learnt is worth sharing and I'll end with a demo you can view/copy.

How Does It Work

Let's start where the last "how to" left off and assume we have a bog standard HTML Form on the page which POSTs the entered user name and password to the URL /names.nsf?Login. No JavaScript is involved thus far.

Now, using this same form, we can now add an onclick event to the Form's login/submit button. Whereas before the button looked like this:

<input type="submit" value="Login" />

It would end up looking like this:

<input type="submit" 
 onclick="DEXT.Session.Authenticate(this.form); 
 return false;" value="Login" />

Notice the "return false" statement in the onclick event. This prevents the browser submitting the form in the usual way. We'll be processing the form in the JavaScript "Authenticate" method instead. Note that this way of doing it means it's still accessible as the form will still work with JavaScript disabled.

The DEXT.Session.Authenticate method looks like this, which you'll no doubt recognise as Prototype-based JavaScript (some bits removed for the sake of brevity).

DEXT.Session.Authenticate = function(frm){
 frm.RedirectTo.value = DEXT.Database.Path+"$icon"; //Load something small!
 $('login-message').update("Authenticating with the server...");
 $('login-form').request({
  onSuccess: function(){
   if( document.cookie.match(/DomAuthSessId|LtpaToken/)){
     $('login-message').update("Authenticated. Reloading page...");
     location.reload();
   }else{
     $('login-message').update('Authentication failed. Please try again.');
   }
  }
 });
}

The Form.request() method used is simply shorthand for the Ajax.request() method.  It saves us having to tell it what URL, method and data to use as it can get all that from the form itself. The other JavaScript libraries all have similar methods available and porting this code to them should be a doddle.

The key to making it all work is simply looking for the existence of a certain cookie once the response is received from the server. If there's a cookie called DomAuthSessId or LtpaToken (for SSO setups) attached to the document then we know the authentication was a success. At this point we reload the whole page. Whether you need to do that depends on how much of the page layout changes once logged-in. If not much changes then you can probably skip this step and have it a truly Ajax-only login process.

An Example

You can see this method in use now in the DEXT app. Hover over the Login link top right (not in IE6 though, yet) and the login form will appear. It should be pre-populated with a valid login. If you press login you'll see a message about it contacting the server and then the page reloading with the name "Dext User" top right and the Login link no longer there.

Now logout using the logout link which replaced the login one from the previous step. When the Login link appears again bring up the login form but alter one of the field values. Try and login now and you should see an error message, while the form remains in place, allowing you to try again.

What Use Is It?

As mentioned this method still reloads the whole page when a login is successful, so why use Ajax, as this, in effect, adds another round-trip to the server that isn't part of a normal non-Ajax login. Well, put simply, it's for the sake of the user. Rather than redirect them to a different interface and out of the application they were in it allows repeated attempts at logging in all from one place.

Lessons I Learnt Along The Way

At first I'd thought I'd be able to examine the page returned to the Ajax request directly and look at its headers. When you login to Domino by POSTing the data the server replies with a HTTP code of 302, which tell the browsers (or Ajax code in this case) where to go next. You're either redirected to the root ("/") of the server or to a URL you specify by passing a value in a field called RedirectTo.

The headers for the immediate response from the server look like this:

HTTP/1.1 302 Found
Server: Lotus-Domino
Date: Tue, 07 Oct 2008 09:31:20 GMT
Connection: close
Location: http://dover/codestore/apps/dext.nsf/$icon
Set-Cookie: DomAuthSessId=E73F7A4E35C7A4A9D2CBA8CA3628F067; path=/

My thought was that I'd be able to examine the headers to this page and if the Set-Cookie header existed and had a value of DomAuthSessId or LtpaToken then hey presto, we're in.

However, from what I've read, it looks like Ajax doesn't let you examine the 302 redirect. Instead it waits until it's fetched the page to which it's redirected and then it lets you process that as the response. Luckily at this point the Set-Cookie header has been processed by the browser and we can inspect the document.cookie from our JavaScript code.

Another lesson I learnt is that you can't POST data to a URL that ends in ?open&login. You can only use a URL ending like that with GET requests. The only time you can POST directly to a login form is if you point the form directly at /names.nsf?login.