Manage Learn to apply best practices and optimize your operations.

Domino and user authentication

This tip details method used to prevent users from being prompted to enter their name/password several times when attempting to access a database that they do not have permission.

This tip details the method I've used to prevent intranet users in a Domino environment from being prompted to enter their name and password multiple times when attempting to access a database to which they do not have permission.

Your environment

You are running IBM Lotus Domino as the back-end server for your intranet (or browser-accessible application). You have defined an ACL on a database that gives certain users rights; some users can edit, other can read, others are blocked entirely.

Incidentally, you cannot use "anonymous" as an ACL setting (except for no access and no checkboxes ticked) if you want this tip to work. In an intranet environment, it is unlikely that you would be allowing anonymous access anyway. Even if you wanted everyone in the Domino directory to have access, you would probably use a group.

I'm assuming that your server document does not allow anonymous access -- that is, Domino will always prompt your users for a name and password (see my note on using IIS below).

The problem

A user, not named explicitly or in a group in the database's ACL, who attempts access to the application will be prompted three times by Domino for a username and password until he gets an "authorization failure" message in his browser.

Figure 1

This is not very useful to anyone -- even if you customize the $$ReturnAuthorizationFailure form.

Why three times? Well this appears to be your browser (Internet Explorer 5+) that does this. When a password is required, it receives a 401 response from the server. The browser then prompts you for a username and password and passes that onto the server. If it gets another 401, it just repeats the process three times (duh!), presumably in the hope you'll type a correct combination of username and password. After three times, Domino gives up.

The solution

Instead of just re-prompting users for a username and password, display a page that details the problem and gives them a route to correct the error -- user-friendly and avoids help desk calls.

How to do it

First, let's get the ACL right.

  1. Give the LocalDomainServers and Notes Administrators manager access.
  2. Give everyone who should have access an entry either as an individual or as a group. You can use as many groups as you need, and set the access as reader, author, editor, etc. Note: For security purposes, the maximum Internet access is usually set to editor.
  3. Create a role of unauthorized.
  4. Set the default access to no access. Check the read and write public documents. Check the unauthorized role for this user.

Here's a screen shot of how it should look:

Figure 1

Now open the database up in design mode.

  1. Create a navigator called WebLaunch.

    By default, the navigator is accessible to public access users. Put another way, there is no way to set or unset this access!

    The WebLaunch navigator contents are not important and never displayed to users. It is used as a hidden navigational tool, simply because you cannot set the launch properties of a database to a form. However, it is a good idea to add a comment to the main navigator body to describe what you are doing for future maintenance.

  2. Create a form called $$NavigatorTemplate for WebLaunch. This form will not be displayed to authorized users, but unauthorized users will get to see the contents. Make sure the form is accessible to public users:

    Figure 1

  3. Create some pass thru HTML on the form saying soothing things like "Oops! Sorry, you don't seem to be authorized to use this application. For further help contact..." Because this is a form (not a page) element, you have access to any CGI and Notes variables you need. I'll leave you with the actual design!

  4. Put the entire HTML in a containing DIV block with an ID of "Error" and "style=display:none". This ensures that your page remains blank until you want to display it.

  5. Now you need to decide whether to display the page or not. Quite simply, if the incoming user has a role called unauthorized, then they get shown the page and not forwarded on. If they do not have this role, then they get transparently forwarded onto the real entry form of the database.

    To determine a user's role, include a Computer For Display (CFD) field at the top of the form, with a formula of @Subset(@UserRoles;-1). This will remove the $$Web Client role that all Web users get. Put the field inside a named SPAN element called UserRole with a "style=display:none" like this:

    <SPAN id="UserRole" style=
  6. Create a further CFD field in a SPAN element called ServerDBPath like this:
    <SPAN id="ServerDBPath" style=
  7. The formula for the CFD field (call it what you will, it's name is never used) is:
    @Name([CN];@ServerName) +
     "/" + @WebDbName +"/"
  8. In the JSHeader write some JavaScript to retrieve this value and either make the currently hidden content visible, or redirect the user to another page. The JavaScript function looks like this:
    function getRole() {
      if (document.getElementById
    ("UserRole").innerText == "[Unauthorised]") {
       //alert ("Permissions failure! 
    Contact Administration Support");
       //display the form contents to the
     user and stop processing!
    style.display = "block";
      }else {
       //alert("Your role is that of " +
    innerText );
       //redirect the user to the required 
    entry point of the database = "http://" + 
    ("ServerDBPath").innerText +

    Note: The two alerts that you can uncomment out for debugging.

  9. In the onLoad section of the form, enter the following JavaScript:
  10. Finally, set the launch properties of the database. When opened in a browser, it opens up a designated navigator called WebLaunch.

    Note: You can always change these names when you've got it all working.

    Figure 1

That's all there is to it! Users with unauthorized (default) permissions get to see a pretty "Unauthorized" page, whilst authorized users don't even know they have been redirected to the true entry page of the application!

Security questions

If you're thinking that users could bypass the security on the database by book marking (or otherwise typing in a URL that goes directly to) a form or view in the database -- it won't happen. This is because the ACL on the database will prevent them and they will get the old, boring prompt for a username and password.

A word of warning, however: access rights are accumulative. So if you assign the role of "[Unauthorized]" to a generic "everyone" group, and then give other groups actual access permissions, then all groups will get the role of [Unauthorized] assigned. Better to just leave the default ACL setting with the role and all groups not having a role assigned at all.

Incidentally, the above restriction doesn't apply if you assign individuals to the ACL; this is because an individual entry overrides all group rights, even when roles have been assigned.

Using this in an IIS environment

If you use Microsoft's IIS (part of Windows 2000) as a "front-end" for all HTTP requests, then this will work just the same -- unless you allow anonymous communication between IIS and Domino (which is not recommended anyway).

In a traditional IIS/Domino setup, IIS handles all HTTP requests (initially anyway). It then passes the requests onto Domino if there is an ".nsf" in the request. Under Domino 5.x, the HTTP task doesn't even run on Domino and all communication is via a special linking module. Under Domino 6.x, the HTTP requests are augmented with some authentication information and passed to Domino as a standard HTTP message -- albeit on a port other than 80 (possibly 81 or 9080, for example).

The advantage of using IIS is that the concept of "anonymous" users has no meaning. By virtue of logging onto your Windows PC, and hence the domain or workgroup, you are "known" to Windows. That user information is what is passed to Domino. You never get prompted to input a name and (intranet) password by Domino when using IIS.

How it works

In case you're not that familiar with the inner workings of Domino, HTML and JavaScript, here is a quick rundown of how this all works.

The user attempts to launch your Web page (in an intranet, for example). He types in, say, "http://intranet/phonebook.nsf," expecting to see the phone book application.

You, the designer, have set the phonebook.nsf application to launch a navigator called WebLaunch when instigated from a browser. Domino finds the navigator, then checks to see whether you've designed a template for it. It finds the $$NavigatorTemplate for WebLaunch form, and uses that as a presentation template to show that navigator. But, because you have not added a special field called $$NavigatorBody, it never actually displays the Navigator, just the form contents (which you have cunningly designed to be user-friendly and helpful).

The form has a computed-for-display role field on it that Domino calculates before converting it to HTML. This now allows you to interrogate the form with JavaScript and extract that value. If you detect that the user has the [Unauthorized] role assigned to him, then he gets to see the (pretty) form. Otherwise he gets transparently and silently redirected to the application's true home page/starting point.

And finally...

Did you get this tip to work? It is unclear in places. I admit I'm aiming it at seasoned Domino/Web developers -- so maybe I've presumed too much.

I'd appreciate any feedback on it, good or bad, so that I can incorporate any suggestions and refine accordingly. For example, would a sample database be of use?

Do you have comments on this tip? Let us know.

This tip was submitted to the tip exchange by member Ralph Bacon. Please let others know how useful it is via the rating scale at the end of the tip. Do you have a useful Notes/Domino tip or code to share? Submit it to our monthly tip contest and you could win a prize and a spot in our Hall of Fame.

Dig Deeper on JavaScript for Lotus Notes Domino



  • Favorite iSeries cheat sheets

    Here you'll find a collection of valuable cheat sheets gathered from across the iSeries/ community. These cheat ...

  • HTML cheat sheet

    This is a really cool cheat sheet if you're looking to learn more about HTML. You'll find just about everything you every wanted ...

  • Carol Woodbury: Security

    Carol Woodbury