When Lotus took Notes and decided to create Domino they obviously needed to add an HTTP server. For a while there was only one option as to which HTTP "stack" you could use. Then, as of Release 5, you had the option of using Microsoft's IIS server in its place. This article is going to discuss the whys and hows of doing this. Although it's been discussed before and is documented in more than one place it's sometimes poorly done and hard to follow. Hopefully this article will contain everything you should ever need to know if you decide to go down this IIS/Domino road.

Why use IIS?

Why would you want to use IIS instead of Domino's default HTTP stack? Well, simply because if we do it this way we can automatically authenticate users with Domino using their NT credentials. This saves both the user from having to remember yet another password combination and the administrators from having to remind/reset them at regular intervals. This can make it yet another "Keeping the boss happy" exercise. Of all the places I've worked they all seem to have the same problem managing user's passwords across different systems. Not a problem if you can show your boss that the next time they enter the intranet it will automatically know who they are. Trust me, it's a winner!

Once you're using IIS you have a whole new market of add-on applications that you can start using. This is down to the fact that a lot of software compaines target their products at the IIS market. For example, take GlobFX's amazing Flash Chart Generator. With IIS running you can start using the plugin to yet more praise from those higher up than you.

Is it hard to do set-up? Not at all, just five simple steps...

Before starting it is assumed that you will be starting on a clean install of Domino R5, on top of a Windows 2000 Server (NT 4 sp4 will also work though).

Step 1: Configuring the ISAPI filter:

1. From the server, start the Internet Services Manager, right-click the Web site for which you want to install Domino for IIS and select Properties.

2. Select the Home Directory tab. Set the option Application Protection to "Low (IIS Process)".

3. Now click the Configuration button. Select the App Mappings tab and Make sure that the option Cache ISAPI Applications is checked.

4. Click the Add button. In the Executable field, enter the full path name of the ISAPI extension file. This file is usually located in the Domino directory and is named NIISEXTN.DLL. For example, if you installed Domino in the default directories, the full path name is as follows:

c:\lotus\domino\niisextn.dll

Alternatively you can use the Browse button and find the file yourself.

5. In the Extension field, enter:

.NSF

6. In the Verbs box, select Limit To, and enter GET,POST

7. Select Script Engine and deselect Check that the File Exists.

8. Click the OK button.

Step 2: Configuring security:

1. If you aren't still in it, start the Internet Services Manager and locate the Web site we are working with.

2. Right-click the Web site and select Properties.

3. Click the Directory Security tab.

4. Click Edit in the Anonymous Access and Authentication Control section.

5. Choose Integrated Windows authentication (NT Challenge/Response) only as below.

Note: Windows NT Challenge/Response, also called NTLM, is a Microsoft-specific protocol supported by Internet Explorer (IE). When a Web user makes a request to the site, IE, automatically sends to IIS the user's current NT logon account name. IIS verifies the name against the NT registry on the IIS server. When a user makes a Domino request, IIS passes to Domino the user's NT name and Domino validates the name using the same process as the native HTTP service.

Step 3: Configure virtual-directory mappings:

1. Start the Internet Services Manager
2. Locate and right-click the IIS Web site before selecting New - Virtual Directory
3. For the Virtual Directory Alias, enter "icons" and click Next
4. Enter the full path to the Domino icons directory, for example: c:\lotus\domino\data\domino\icons
5. Click Next
6. You do not need to change the default permission settings of Read and Script Access; however, you can make changes if desired
7. Click Finish
8. Repeat these steps for the Java applet directory. Specify "domjava" as the alias name and specify the path to the applet directory, for example: c:\lotus\domino\data\domino\java

You may also need to map other "non-standard" directories, see the Developer's Notes section below.

Step 4: Configure the Domino Server:

Depending on how you installed the Domino server you should have very little to do.

If it's a standard Domino install then the first thing to do is disable the HTTP task. You can do this at the console by typing "tell http quit" at the server console.

This will only stop it for the current server session though, so we need to make it permanent by removing HTTP from the ServerTasks line in the Notes.ini file.

If you are going to do a clean Domino install then you will be asked if you want to use IIS as the system's default HTTP stack during install. Say yes and that you want to use port 80.

As a final precaution, go to the Server Document, find the Internet Protocols tab, open the second of the sub-tabs ("Domino Web Engine"). Check the settings are the same as those illustrated below.

Also check that in the "Web" tab of the "Internet Ports" tab of the "Ports" tab the HTTP settings are the same as displayed below:

Step 5: Configure the Domino Users:

The final and probably the most important step is to make the necessary changes to the Person document in the Domino Directory (NAB) of every user that will be authenticating with this server.

For Domino to authenticate a Web user using NT Challenge/Response (NTLM), the user's NT domain and account name combination must be registered in Domino. If Domino is using Person documents in the Domino Directory to authenticate users, the documents must contain NT account names as aliases in the User Name field. For example, if Jake Howlett has a Notes ID in the "USR/EPSILON" Organisational Unit of the "EITS" Organisation and has an NT user account name of "jakehowl" in the "EPSILON" NT domain, the User name field in Jake Howlett's Person document needs to contain:

Jake Howlett/USR/EPSILON
Jake Howlett
EPSILON\jakehowl

This allows Domino to authenticate the NT user EPSILON\jakehowl as the Domino user Jake Howlett/USR/EPSILON.

Note that Domino does not use its own HTTP Internet password. IIS passes only the NT account name to Domino and Domino trusts that IIS verified the user's authenticity. Sorry there is now no need to worry about users who forget their Domino HTTP passwords.

Note that NT Challenge/Response uses the following guidelines: When NT Challenge/Response is the only authentication method enabled, only IE users can access the Web site. Anonymous access is not possible since IE automatically sends the user's NT account name of a logged in user upon every request. The Web user must be a registered NT user.

IMPORTANT: The first alias in the User Name field of the Person document must be the name that is used as the person's entry in the ACL of the "secured" database (as in the above example).

Note 1: Understanding Anonymous

If you've followed the above guide step-by-step you will be at a point where people not registered in the NAB or registered but without their NT credentials in the UserName field will have no access. Even if the ACL to your databases specifies that "Anonymous" user has access to the database they will not get in as IIS doesn't allow Anonymous access and hence forces all requests to be Authenticated in some way.

So how do I let the Anonymous user in?

Well, the first thing to do is turn on the "Anonymous access" setting so that IIS will allow people access without them having to authenticate.

Now, when a user requests a page to which the ACL allows Anonymous access, they will get in. They will not be authenticated at this point however. To do this and work out who they are you either need to append "&Login" to the URL or perform an operation for which Anonymous has no rights, i.e ?EditDocument. In these two scenarios the browser will authenticate with Domino via NT's Challenge/Reponse (NTLM) mechanism.

Note that this authentication is not session-based. It is only performed on a by-request basis. If you navigate to a URL without "&Login" from one that did they will return to being a user called "Anonymous". Similarly, if you go from Anonymous in an "OpenDocument" to an "EditDocument" you will be forced to Authenticate. Go back from here to "OpenDocument" and you will return to being Anonymous.

In the situation where users are forced to authenticate and Domino says no, as they don't have the right privileges, then the user will be presented with the following Login prompt.

Note 2. Things for developers to take account of:

1. The way in which IIS knows that a certain request is intended for the Domino server is the presence of the ".nsf" portion of the URL. This mean that you can no longer use URLs like:

http://epsdomsvr01/802569F200453B39/all?open

Which uses the Replica ID of the database to replace the file path of the NSF file in a URL that would normally look like:

http://epsdomsvr01/codestore/store.nsf/all?open

So, ALL databases that are to be accessed via the web and in which there may be URLs in this format. Must be re-engineered. Sad but true. An alternative is to use URLs of this format:

http://epsdomsvr01/__802569F200453B39.nsf/all?open

2. Depending on how and if you use the default Domino HTML directory on the file system (X:\Domino\Data\Domino\HTML\) you may need to move it or map to it. If you have an images folder within it then the URL to an image when using the Domino HTTP server is like so:

http://epsdomsvr01/images/worldmap.jpg

However, as there is no ".nsf" in this URL, IIS won't know that it should pass the request to Domino. The easiest way round this is to move the whole of the contents of the Domino HTML directory in to IIS's root folder (X:\Inetpub\wwwroot\). Alternatively you could map a folder called images to the images folder, but you would need to do this for all folders in Domino's root HTML directory.

Apart from that it should all be exactly the same. Happy surfing!

Summary

If you've got this far I assume you're interested in this approach. After all, using IIS isn't everybody's cup of tea. Personally I think it's a great time saver and something you should at least bring up as an idea in your next team meeting. Suggest a trial server maybe to see how useful it can be not having to sign in all the time. If the team nerd pipes up about how bad Microsoft prodcuts are you might want to suggest that they get a life.

I'll be back soon to discuss using those fancy Flash charts I mentioned earlier...