Wednesday, July 29, 2009

Setting up Domino to work with Microsoft IIS servers

Setting up Domino to work with Microsoft IIS servers

To use a Microsoft® IIS server as a front-end machine, you must install the IBM WebSphere® Application Server plug-in for IIS on the IIS server. The plug-in files are packaged with the IBM® Lotus® Domino® 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 IBM® 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 Information Services (IIS) Manager configuration tool. On Microsoft® Windows® 2000/2003, 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

  1. Download the Web server plug-in files for WAS from IBM software downloads - Trials and demos Web site.

IBM software downloads - Trials and demos

Follow the instructions, according to platform, that display on the Web site.

  1. Copy the plug-in files to the IIS server.
    1. Copy data/domino/plugins/plugin-cfg.xml to c:\WebSphere\AppServer\config.
    2. Copy data/domino/plugins//w32/iisWASPlugin_http.dll to c:\WebSphere\AppServer\bin.
  2. Start the Internet Information Services Manager application.
  3. 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.
  4. In the Alias field, enter "sePlugins."
  5. In the Directory field, browse to the WebSphere bin directory (C:\WebSphere\AppServer\bin).
  6. For access permissions, check "Execute" and uncheck all other permissions.
  7. Click Finish. A virtual directory titled "sePlugins" is added to your default Web site.
  8. In this step, follow the appropriate procedure for your version of Windows.

On Windows 2000:

    1. Right-click the machine name in the tree on the left and select Properties.
    2. On the "Internet Information Services" tab, select "WWW Service" in the "Master Properties" drop down box and click Edit.
    3. In the "WWW Service Master Properties" window, click the "ISAPI Filters" tab.

On Windows 2003:

    1. Right-click the individual web site to enable for the plugin.
    2. Click "ISAPI Filters."
  1. Click Add. This opens the "Filter Properties" dialog.
  2. In the "Filter Name:" field, type "iisWASPlugin."
  3. In the "Executable:" field, click Browse. Open the WebSphere bin directory and select "iisWASPlugin_http.dll."
  4. Close all open windows by clicking OK.
  5. In this step, follow the appropriate procedure for your version of WebSphere.
    • For WebSphere 4.0/5.0 plugins:

Open the Windows registry file and create the following key path: HKEY_LOCAL_MACHINE - SOFTWARE - IBM - WebSphere Application Server - . Select this last key 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)

    • For WebSphere 6.0 plugins:

Create a text file that contains the full path to the plugin-cfg.xml file (including the file name) and save the text file in the C:\WebSphere\AppServer\bin directory as "plugin-cfg.loc." For example:

c:\WebSphere\Appserver\config\plugin-cfg.xml

  1. To enable the plug-in for additional Web sites, repeat Steps 4 through 8.

For more information, see Configuring Microsoft Internet Information Services (IIS) in the WebSphere Application Server Information center.

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 IBM® Lotus® 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.

To configure plugin-cfg.xml

  1. Open plugin-cfg.xml in Notepad.
  2. Modify the 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 back-end server's HTTP task. For example:

  1. Add these directives to the top of the section. These directives specify common URL patterns needed for accessing Domino Web applications.

If your Domino application requires additional namespaces, you can create 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.

For more information, see plugin-cfg.xml file in the WebSphere Application Server Information center.

To configure the Domino server to work with Microsoft IIS

On the back-end IBM® Lotus® 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 front-end 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 an IBM® Lotus® Domino® back-end server, Web applications are subject to both IIS security and Domino security. After IIS authenticates a user based on the Microsoft® 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).
  • SSL

IIS requires user authentication in order to control access to resources owned by IIS such as the file system and Active Server Pages. If a user requests access to a Domino resource, the IIS plug-in passes the authentication information to Domino. The information passed depends on the combination of authentication methods enabled on IIS. After the information is passed, Domino authenticates the user according to the procedures discussed in the topic "Details of Microsoft IIS security." All of the Domino directory options are available, such as using multiple Domino Directories and LDAP directories.

To set up security on the IIS server:

  1. Start the Internet Services Manager
  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.

For more information on the plugin, including installing it on Microsoft Windows Vista and Windows 2008, see Installing Web server plug-ins in the WebSphere® Application Server Information center.

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 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 when setting up name-and-password authentication.

Anonymous Access uses the following guidelines:

  • The Web user does not need to be a registered 2000/2003 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.

Basic Authentication

When using Basic Authentication, IIS verifies the user credentials that the browser sends as a valid 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 Windows 2000/2003 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

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 an IBM® Lotus® 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 Windows 2000/2003 user.
  • If you want to match the Windows user to a Domino Person document, You need to add the user's 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.

SSL

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 the user to Anonymous access.