Weblog
18/2: Domino and IIS Configuration
I have taken the liberty of copying the Domino 6.5.1 help pages and then correcting errors. To be fair, most of the errors that were in the 6.03 help had been fixed.Please note that where the angle bracket has been used for XML tags, I have had to include a space character after the " < " character to prevent the browser trying to interpret it as HTML. I have highlighted text in red if it had errors in the 6.03 or 6.51 help.
Setting up Domino to work with Microsoft IIS servers
To use a Microsoft IIS server as a front-end machine, you must install the WebSphere Application Server 4.0.3 plug-in for IIS on the IIS server. The plug-in files are packaged with the Domino 6 server and must be copied from the Domino server to the IIS server. After you copy the plug-in files, you must configure the plug-in, then configure the Domino server to work with the plug-in IIS. You do not need to install any other WebSphere components to use the Microsoft IIS plug-in.
To install the WebSphere plug-in on an IIS server
Do the following to install the WebSphere plug-in on the IIS server and enable it for a Web site. Before beginning this procedure, you should be familiar with the Internet Services Manager configuration tool. On Windows NT this tool is accessed through the Microsoft Management Console.
| 1. | Create the following directory structure on the IIS machine (you may use any drive); |
| C:\WebSphere\AppServer\bin C:\WebSphere\AppServer\config C:\WebSphere\AppServer\etc C:\WebSphere\AppServer\logs | |
| 2. | Copy the following files from the Domino server to the IIS server: |
| a. | Copy data/domino/plug-ins/plugin-cfg.xml to c:\WebSphere\AppServer\config. |
| b. | Copy data/domino/plug-ins/was4/w32/iisWASPlugin_http.dll to c:\WebSphere\AppServer\bin. |
| c. | Copy data/domino/plug-ins/was4/w32/plug-in_common.dll to c:\WebSphere\AppServer\bin. |
| 3. | Start the Internet Service Manager application. |
| 4. | Create a new Virtual Directory for the Web site instance you want to work with WebSphere. To do this with a default installation, expand the tree on the left until you see "Default Web Site." Right click on "Default Web Site" and select New - Virtual Directory. This opens the wizard for adding a Virtual Directory. |
| 5. | In the Alias field, enter "sePlugins." |
| 6. | In the Directory field, browse to the WebSphere bin directory (C:\WebSphere\AppServer\bin). |
| 7. | For access permissions, check and uncheck all other permissions. |
| 8. | Click Finish. A virtual directory titled "sePlugins" is added to your default Web site. |
| 9. | Right click the machine name in the tree on the left and select Properties. |
| 10. | On the "Internet Information Services" tab, select "WWW Service" in the "Master Properties" drop down box and click Edit. |
| 11. | In the "WWW Service Master Properties" window, click the "ISAPI Filters" tab. |
| 12. | Click Add. This opens the "Filter Properties" dialog. |
| 13. | In the "Filter Name:" field, type "iisWASPlugin." |
| 14. | In the "Executable:" field, click Browse. Open the WebSphere bin directory and select "iisWASPlugin_http.dll." |
| 15. | Close all open windows by clicking OK. |
| 16. | Open the Windows registry file and create the following key path: HKEY_LOCAL_MACHINE - SOFTWARE - IBM - WebSphere Application Server - 4.0. Select 4.0 and create a new string value "Plugin Config". Set the value for this variable to the location of the plugin-cfg.xml file (C:\WebSphere\AppServer\config\plugin-cfg.xml) |
| 17. | To enable the plug-in for additional Web sites, repeat Steps 4 through 8. |
To configure the WebSphere plug-in
The WebSphere configuration file WebSphere\AppServer\config\plugin-cfg.xml controls the operation of the plug-in. In order for the plug-in to relay requests to the target Domino server, you must add directives to plugin-cfg.xml to define a transport route to the server, and pattern rules for the URL namespaces that identify requests which are to be relayed to Domino. The plug-in will only relay requests that match a namespace rule. All other requests will be handled by the front-end Web server. So to configure the plugin:
| 1. | Open plugin-cfg.xml in Notepad. |
| 2. | Modify the < Transport> element to target the appropriate Domino server. To do this, change the Hostname and Port parameters to the proper values required for the plug-in to reach your Domino server's HTTP task. For example: < !-- Server groups provide a mechanism of grouping servers together. --> < ServerGroup Name="default_group"> < Server Name="default_server"> < !-- The transport defines the hostname and port value that the web server plug-in will use to communicate with the application server. --> < Transport Hostname="mydomino.server.com" Port="81" Protocol="http"/> < /Server> < /ServerGroup> |
| 3. | Add these directives to the top of the < UriGroup> section. These directives specify common URL patterns needed for accessing Domino Web applications. < UriGroup Name="default_host_URIs"> < Uri Name="*.nsf*"/> < Uri Name="/icons/*"/> < Uri Name="/domjava/*"/> < Uri Name="/execcgi/*"/> < Uri Name="/cgi-bin/*"/> < Uri Name="/servlet/*"/> < Uri Name="/download/*"/> < Uri Name="/mail/*" /> |
If your Domino application requires additional namespaces, you can create < Uri> directives for those patterns also.
Note All the WAS plug-ins automatically reread the configuration file once a minute to pick up changes. If you don't want to wait that long, you must stop and restart the front-end Web server. In the case of the IIS plug-in, you must stop the World Wide Web Publishing Service from the Windows services control panel, then restart the Web site from the Internet Services Manager. Just stopping and restarting the Web site by itself won't work because the plug-in DLL won't be reloaded.
To configure the Domino server to work with Microsoft IIS
On the back-end Domino server, add the following line to NOTES.INI:
HTTPEnableConnectorHeaders=1
This setting enables the Domino HTTP task to process the special headers added by the plug-in to requests. These headers include information about the frontend server's configuration and user authentication status. As a security measure, the HTTP task ignores these headers if the setting is not enabled. This prevents an attacker from mimicking a plug-in.
Setting up security for Microsoft IIS
When you have set up an IIS plug-in and a Domino backend server, Web applications are subject to both IIS security and Domino security. After IIS authenticates a user based on the NT Windows account registry, those credentials, if any, are passed to Domino for user authorization.
Microsoft IIS supports four methods of user authentication. The Domino plug-in configuration supports all except Digest authentication.
- Anonymous access (the user does not enter a name or password)
- Basic Authentication (the user enters a name and password)
- Digest authentication (an enhanced version of Basic authentication available only on Windows 2000). The Domino plug-in configuration does not support this authentication method.
- Integrated Windows authentication (a special protocol supported by Microsoft Internet Explorer. On NT, this protocol is called Windows NT Challenge/Response)
- SSL
For information on setting up security options on the Domino server, see the topic "Overview of Domino security" within the Admin help.
To set up security on the IIS server:
1. Start the Internet Services Manager (or Microsoft Management Console on NT). 2. Right-click the IIS Web site and select Properties. 3. Click the Directory Security tab. 4. Click Edit in the Anonymous Access and Authentication Control section. 5. Choose one or more of the authentication options and click OK.
Details of Microsoft IIS security options
Anonymous Access
Anonymous Access lets Web users access a Web site without a user name or password. IIS always maps anonymous Web users to a specific NT anonymous user account, which you can configure. If Anonymous Access is the only IIS authentication method enabled, IIS does not use any user credentials -- that is, a user name and password -- sent by the browser for authentication, but the IIS plug-in passes the credentials to Domino, and Domino will authenticate the user according to the normal procedure for Web users. If an anonymous user attempts to access a Domino resource that requires authentication, Domino will respond appropriately according to the security options you have set for the Domino Web site (a Basic name-and-password challenge, or a session authentication login page). Therefore, if you want Domino to completely handle user authentication, you should enable Anonymous Access as the only security option for the IIS Web site.
For information, see the topic "Name-and-address authentication for Internet/intranet clients" in the Admin help.
Anonymous Access uses the following guidelines:
- The Web user does not need to be a registered NT user.
- If you want a user to access secure resources, the Web user must be a registered Domino user and the user must have an Internet password.
When using Basic Authentication, IIS verifies the user credentials that the browser sends as a valid NT user account. If Basic Authentication is the only IIS authentication method enabled, IIS requires all browser requests to have credentials -- anonymous access is not allowed. Whenever a user sends a Domino request, the IIS plug-in passes the user name to Domino and informs Domino that the user has been authenticated by IIS. Such a user is called a "pre-authenticated" user. The plug-in passes the pre-authenticated name exactly as the user entered it in the browser. Domino then attempts to look up that name in its directories. Since IIS has already verified the user's password, Domino does not use the Internet password stored in the user's Person document or LDAP entry.
If Domino finds the name in a Domino Directory, then Domino uses the primary name in the Person record for authorization (ACL checking). If Domino does not find the name, then Domino uses the pre-authenticated name as-is for authorization.
In both cases, Domino builds the user's group list from the set of groups in the Domino Directory which include the user as a member, and Domino also adds the special group "-WebPreAuthenticated-" to the group list. You may use -WebPreAuthenticated- as a group entry in database ACLs and other access lists.
Note If you want to list IIS users by name in database ACLs, you must be careful to use the correct form of the name. Use the primary name if the user is listed in the Domino Directory, or the IIS pre-authenticated name if the user is not in the directory. Remember that if a user is listed by name in an ACL and is also a member of a group in the ACL (including "-WebPreAuthenticated-" or any other group), the name entry takes precedence over the group entry.
In summary, Basic Authentication uses the following guidelines:
- Anonymous access is not allowed.
- The Web user must be a registered NT user.
- The Web user does not have to be a registered Domino user.
- Domino does not use the user's Internet password.
- The Web user is automatically assigned to the -WebPreAuthenticated- group.
Integrated Windows authentication 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 Windows logon account name. IIS verifies the name against the Windows registry on the IIS server. When a user makes a Domino request, the IIS plug-in passes to Domino the user's Windows name and Domino processes the pre-authenticated name as described above for Basic authentication.
Windows account names use the form domain\username or machinename\username -- for example, SALES\JSmith. If Domino is using Person documents in the Domino Directory to authenticate the Windows users, the documents must contain the exact Windows account names as aliases. For example, if Joe Smith has a Notes ID in the "CorpSales" domain and a Windows user account in the "SALES" Windows domain, the User name field in Joe Smith's Person document needs to contain:
Joe Smith/CorpSales
SALES\JSmith
This allows Domino to authenticate the Windows user SALES\JSmith as the Domino user Joe Smith/CorpSales.
In summary, integrated Windows authentication uses the following guidelines:
- If this 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 Windows account name on every request.
- The Web user must be a registered NT user.
- If you want to match the Windows user to a Domino Person document, You need to add the user's NT Windows account name as an alias to the Person documents.
- Domino does not use the Internet password.
- The user is automatically assigned to the -WebPreAuthenticated- group.
If you enable SSL on a Web server, IIS handles the actual SSL connection. However, if a Web user provides a client certificate, the IIS plug-in passes the certificate to Domino and Domino uses the certificate to authenticate the user. If Domino cannot find a certificate for the user, then Domino will downgrade th e user to Anonymous access.
