Custom Login Forms - A How-To

In my bid to follow up things I've talked about in the past I want to talk about what I found out about using custom login forms with Domino. Something I was talking about late on in June.

Now, there are numerous ways of doing this and I just want to describe what I think is the best way. It's not perfect but it's the best in my eyes.

This is a game best played Domino's way. Sure, we can simply add a couple of fields to a form and POST it to a URL ending in &Login. This works but it's not ideal. What happens when a session expires or authorisation and/or authentication fail? We end up where we started, with Domino's ugly login form (I'm writing this assuming we're using session-based authentication).

I found it's best to leave the authentication to Domino. How do we do this and still get to customise our forms? Using Internet Site documents.

This is where the big problem comes in. To use custom login forms with Domino you need a separate DNS entry for each application/site. This is ok for a true website, but not so good for things like internal company applications. Let's say you have two internal apps, called Prism and Arc, on a server called Pluto, which is part of the domain rockall.com. Traditionally you might have users access them directly via URLs like http://pluto.rockall.com/prism.nsf or http://pluto/arc.nsf. To use custom login forms for each application we need an Internet Site to govern each. To do this, each will need its own DNS entry.

Obviously you need to be on good terms with the Sys. Admins to get this setup. Without them on your side you're going to be out of luck.

Once you've got DNS aliases setup you'll be able to access the apps directly via URLs like http://prism.rockall.com or simply http://arc/. There's an added bonus to this in that it makes it easy for users to remember where the apps are. If they forget the support guys just have to explain they type the name in to the browser!

So, you've got the DNS entries setup. Now you need to setup the Domino server. Here's how:

First thing to do is add a new Web Site document to the server (you need to be using a server that uses Internet Site documents in the first place!):

In this document you make all the other changes for the website, like default homepage etc.

Then we need to map a login form to this new Web Site. To do this we need to switch to that server's Domino Config (domcfg.nsf) database (create one if it's not already there). From this database create a new Sign-In Form Mapping document, like so:

There's a gotcha involved in this bit. See the field that says Web Site/Virtual Server? Well the hint for that field says: "If using Web Site configuration documents, specify the name of the Web Site this mapping applies to. Otherwise specify the Virtual Server name or IP address". From the mapping document shown above you would think this field entry would simply be "Prism". As hard as I try I can't Domino to recognise the mapping by Web Site name and have to use the DNS name instead.

This is ok until you try to map login forms for both //prism/ and //prism.rockall.com/. The web Site documents allows you to enter them both but the Mapping document will only allow one entry at a a time. So, you need two Mapping documents if you want to allow users to enter either address. Like so:

But, hey, it works. You can have a completely customised login form in your application. Because the form actually lives inside your NSF it's easy for it to share the same look, feel and layout as the rest of the application. All you need to add to it are two fields - one called username, one called password - and a "submit" button.

Obviously this is Domino and the way it works isn't quite as polished as you'd like, but at least it can be done. Any questions, let me know...


    • avatar
    • YoGi
    • Tue 2 Aug 2005 06:55 AM


    Personally, I use AJAX to log users with a custom login form, so that I can handle the case the authentification failed. But it doesn't work for session expiration.

    • avatar
    • MikaSq
    • Tue 2 Aug 2005 08:00 AM

    You could also probably use HTTP_Referer and Path_Info CGI-variables to build intelligent Login Form you need.

    I haven't tested the HTTP_Referer variable in such environment, so I am not sure of it though.

  1. Rather than programming a different login form for every application at my company we opted to integrate web applications into the general company intranet.

    User's are already used to logging into the intranet (it's based on Domino and not all information is readily available to everyone, so anonymous access is not enabled for any databases).

    To enable single sign on between domino and non-domino applications (like SAP-apps) we use WebSeal as a front to let the user authenticate and then transfer the WebSeal authentication to domino by entering the WebSeal identity in the domino groups.

    The custom login form is just modified to display a message that a user is trying to access a restricted page since authentication is handled by WebSeal.

    Another advantage is that you can also authenticate people that are not in your domino directory but have a userid and can log into the intranet and all applications using the same userid and password.

    • avatar
    • Robert Prinz
    • Tue 2 Aug 2005 03:04 PM

    What can i do when i don't use the option:

    "using session-based authentication"

    • avatar
    • Jake
    • Tue 2 Aug 2005 03:20 PM

    Not much Robert. You could make your own form that posted to a URL like:


    But this is disabled in IE that's been hotfixed recently.

    And then if authentication fails the user is still prompted with the old grey login box.

    You're stuck with what you've got!

    • avatar
    • MikaSq
    • Wed 3 Aug 2005 02:25 AM

    In Domino 5.x (not sure or 6.x and 6.5.x) when you didn't use session-based authentication user could login to all databases in the same directory in the same session.

    Ie. If you login to {Link} you could use {Link}

    However if you try to login to {Link} you had to authenticate again.

    I would suppose that this is non-session based authentication in Domino 6-series.

    • avatar
    • harkpabst_meliantrop
    • Wed 3 Aug 2005 03:58 AM

    I don't even think, that providing a custom login form when not using session based authentication is such a good idea. Isn't it still simple authentication that is used then? And that means that login info is transfered just encoded (not encrypted) with every browser request. Also - as far as I know - there is no way to define a realm for which the authentication is valid.

    • avatar
    • BrianP
    • Tue 13 Jun 2006 03:36 PM

    Is there any documentation on "adding a couple of fields to a form and POST it to a URL ending in &Login"

    Which fields do I need? the same ones on the $$LoginUserForm?


    • avatar
    • Jake Howlett
    • Tue 13 Jun 2006 05:03 PM

    Two fields needed - Username and password

  2. My login form works, but it doesn't automatically show up. How can you force the database to go to this site (i.e. the login form) first when a user accesses the database via webbrowser?

    Thank you


  3. Anyone have any luck with mobile browsers?

Your Comments


About This Page

Written by Jake Howlett on Tue 2 Aug 2005

Share This Page

# ( ) '


The most recent comments added:

Skip to the comments or add your own.

You can subscribe to an individual RSS feed of comments on this entry.

Let's Get Social

About This Website

CodeStore is all about web development. Concentrating on Lotus Domino, ASP.NET, Flex, SharePoint and all things internet.

Your host is Jake Howlett who runs his own web development company called Rockall Design and is always on the lookout for new and interesting work to do.

You can find me on Twitter and on Linked In.

Read more about this site »

More Content