Some essential Notes.ini parameters

I’ve been doing a fair amount of work with Domino and IIS recently, implementing a single-sign-on Active Directory authentication solution for an academic institution.  It has been interesting work, challenging for sure, and I definitely bear the scars.  As ever, there is a good mix of well-documented IBM information, great third-party posts and HOWTOs, and a load of undocumented stuff that is only found by trying, testing and failing!

This organisation wanted to use a number of well established Domino web applications on multiple Domino 6.5.x servers, but to authenticate their users via Active Directory rather than against the Domino Directory.  They get a large intake of new users every year (the new student year group) and the process of managing both Active Directory and Domino passwords was proving too much.  In most cases I would suggest that Domino Assistance is used to provide secondary authentication against the AD LDAP, but in this case it was imperative that the application tracked the users’ usage via their Domino user IDs rather than just their AD names.  All users are in both directories, and the Domino short-name is always set to the AD username.

Therefore, we proposed the use of an IIS server running on Windows 2003, configured with the WebSphere HTTP plug-in, using Verisign SSL certificates, transferring the users through to Domino at the back end.  This is a well-trodden path that has been around since the Domino R5 days, and is supported all the way through to the latest R8.x releases.  There is a wealth of documentation out there – I’d highlight Warren Elsmore’s excellent summary, DotNSF’s thorough howto, and the Domino Infocenter’s overview as great starting points.

As ever, we started with a test environment, a vanilla Win2003 VM, and a test Domino server with copies of the Domino Directory and the applications.  We also created a standard Domino Discussion DB as a check database.  We then configured IIS as I always do.  All looked to work well – the users could authenticate against AD (using basic authentication), the plug-in passed them through to domino, and a javascript redirect pushed them to the correct URL (the discussion databse).  However, in this case, despite following the documented steps thoroughly, checking and checking again, I just could not get the test environment to correctly match the AD test user to the Domino user.  In some cases the results were not consistent, in other cases, it always picked the wrong user.  We could demonstrate this by creating a new topic or response in the discussion database.

e.g. The user ‘Joe Lloyd’ logs in via AD as the user ‘joel’ ({first name}{initial of last name}) which is their sAMAccountName in AD and their short name in the Domino Person record.  They are authenticated correctly and can access the discussion DB, but when creating a new topic, they are shown as being logged in as ‘Joel Thomas’ (for example).  However on another occasion, they were shown as being logged in as ‘Peter Joelsen’.

Can you see the problem?  The IIS/Domino transfer is selecting a user that matches with the AD name, but not necessary the short name (which is unique by the way).

A couple of trace Notes.ini parameters really helped debug this (which many of you will know):
WEBAUTH_VERBOSE_TRACE=1
WEBSESS_VERBOSE_TRACE=1

They do produce a LOT of output in the console log, so they’re not advised on production servers for any length of time, but for debugging things, they make life a lot easier.

From this, it looked as though IIS was passing through the sAMAccountName (e.g. ‘joel’) and Domino was simply doing a full-text search of the $Users view in the Domino Directory.  Certainly a search for ‘joel’ in the Directory using a standard FT dialog brought up four possible matches, two of which we had seen in our testing.  Setting the server to only accept “fewer matches” in the server doc didn’t help as the User Name field would still be searched, and thus match ‘Joel Thomas” as well as the ‘joel’ short name.

So, what to do?  Well, it turns out that there are two almost undocumented Notes.ini variables that can really help:
NABWebLookupView=
NoAmbiguousWebNames=

The former tells Domino to authenticate web users (and WAS Plugin users) against a specified view in the Domino Directory, rather than against $Users.  The latter states that only unambiguous matches should be allowed, rather than simply taking the first one that it finds.  In our case, we knew that we wanted to only authenticate against the AD ID stored in the short name field.  Therefore, I created a hidden view in the Domino Directory, {$Shortname} which has just one column set to display the Shortname field from the person docs.  Then I set the new parameters to be:
NABWebLookupView=$Shortname
NoAmbiguousWebNames=1

Once the server was restarted, the authentication worked as desired.  Note that this new lookup also applies to users logging directly into the Domino website as well as IIS/IHS users, so you may need to train existing users to use their short name.  Secondly, these parameters do not seem to work (at lest on 6.5.x) when Directory Assistance is enabled – so ensure that there is no DB listed in the Directory Assistance field in the server doc.

The new directory independence slated for Domino 9 will certainly help in this area, but until then, this seems a pretty good solution.  I’d be happy to help out if anyone has any questions…

Stuart McIntyre is a Senior Strategist at Fostering Community Limited. He curates a number of product-focused news sites, is a lapsed podcaster, founded the Social Connections user group and regularly speaks at conferences and events. This blog represents his own slightly-eccentric and usually-controversial opinions!