Technical Notes

Integrating Reflection for the Web with IIS
Technical Note 2195
Last Reviewed 31-Oct-2008
Applies To
Reflection for the Web 2008 (All Editions)
Reflection for the Web version 8.0 through 9.x
Microsoft Windows Server 2003
Microsoft Windows 2000 Server
Microsoft Internet Information Server (IIS) version 6.0
Microsoft Internet Information Server (IIS) version 5.0
Summary

This technical note describes how to integrate Reflection for the Web with an existing Microsoft Internet Information Server (IIS) running on Windows Server 2003 or Windows 2000 Server. This technical note assumes that IIS has already been installed on your server.

How this Technical Note Is Organized

The information in this technical note is organized into the following sections:

Reasons to Integrate Reflection and IIS

By default, Reflection for the Web installs and uses the Jakarta Tomcat web server, so you do not need to integrate Reflection for the Web with IIS to use Reflection. However, you may choose to integrate Reflection and IIS for one or more of the following reasons.

• When integrated with IIS, Reflection can be configured to use the standard IIS ports. This enables you to open fewer ports in your firewall, thus improving security.

• Integrating with IIS enables you to take advantage of the IIS Single Sign-on (SSO) functionality.
• Integrating with IIS enables you to use your existing SSL web server certificates with Reflection for the Web. In contrast, when using the default Jakarta Tomcat web server, you must import your existing IIS certificates into Reflection or obtain additional SSL web server security certificates.

Prerequisites

Note the following prerequisites.

• IIS must be installed and running.
• In order for the Reflection IIS Wizard to interact with IIS, the IIS server must still have the default web site entry "<Default Web Site>.” If you have removed the <Default Web Site> from IIS, you must redefine a site with this name before proceeding.

• You must be logged in as a user with administrative privileges.

Recommended Resources

Attachmate Technical Support recommends that you review this entire technical note before you begin installing Reflection for the Web or configuring your installation. It is also recommended that you review the Installation Guide, which is available in the Reflection for the Web product and at http://support.attachmate.com/manuals/wthdocs.html.

For a complete list of Reflection for the Web information resources, see Technical Note 1668.

How Security Certificates are Integrated

When Reflection for the Web is installed, a Tomcat self-signed certificate is created. When Reflection is integrated with IIS, the IIS certificate will be used.

Tomcat and IIS Certificates

Reflection for the Web uses a Tomcat or IIS certificate based on the following conditions:

• The Tomcat certificate is only used for HTTPS when Tomcat is used as the web server.
• When Reflection is integrated with the IIS web server, Reflection uses IIS and the IIS-configured server certificate for HTTPS communication. The Tomcat certificate is ignored.
• Although the Tomcat self-signed certificate is not used after IIS integration, we recommended you do not delete this certificate.
• Once integrated with IIS, the expiration status of the Tomcat certificate does not affect the Reflection installation.

Verifying HTTPS Support in IIS

HTTPS must be enabled in IIS in order to encrypt communications (including user names and passwords) sent between client computers and the Reflection management server. It is important to confirm that your IIS web server is configured to support HTTPS connections; follow these steps:

Note: While HTTPS is recommended for security reasons, if you are evaluating Reflection for the Web and don't have a CA signed certificate, use HTTP. If using HTTP, no changes are needed; skip to Installing Reflection for the Web.

1. For Windows Server 2003: Click Start > Administrative Tools > Internet Information Services Manager.

2. Double-click the icon representing your web server. (If you are using Windows Server 2003, you must also double-click the Web Sites folder.)
3. Right-click the icon for the web site to which you want to add Reflection for the Web, and select Properties.
4. Select the Directory Security tab.

1. Open the Directory Security tab (steps 1-4 above). Click Server Certificate, and follow the instructions in the web server certificate wizard to generate a certificate request.
2. Submit the certificate request to a CA to obtain a web server certificate.
3. After you have obtained a web server certificate from a CA, run the web server certificate wizard again to process the certificate returned by the CA.

1. Start the Administrative WebStation and login as Administrator.
2. In the left-navigation bar, click Tools > Settings, and then click the Security tab.
3. In Reflection for the Web 2008, under "Management server access protocol," select Require HTTPS, and then click Save Settings at the top or bottom of the Security Setup page.

Installing Reflection for the Web

To integrate Reflection with IIS, you must use the Reflection automated installer to install Reflection onto your web server computer (Microsoft Windows Server 2003 or Windows 2000 Server). You will be prompted to integrate with IIS during the installation process. You can choose to integrate during installation or any time after you complete installation by running the IIS Wizard utility, which is installed automatically. See Running the IIS Wizard (if integration was skipped during installation).

Note the following

• For IIS integration, you must use the Reflection for the Web automated installer.
• For Reflection integration with IIS, the IIS server must have a site called <Default Web Site> defined. For further details, see Prerequisites.

Uninstalling Earlier Reflection for the Web Versions

Before installing Reflection, you must uninstall any previous version of Reflection for the Web using the Windows Add/Remove Programs utility. For information about upgrading earlier versions of Reflection for the Web, see the Reflection for the Web Installation Guide.

Required Choices During Installation

Begin the automated installer and follow the prompts. Use the following information to help you complete the installation and integration.

To integrate Reflection for the Web with your IIS installation, you must install and configure the following Reflection components and port settings.

Note: The installation wizard requires that you enter detailed information pertaining to your environment. See the Reflection for the Web Installation Guide for specific installation instructions and an installation checklist.

Components to Install

While running the installation wizard, you can select which features of Reflection for the Web you would like to install. For this installation, you must install the following features:

• Emulation & Administration
• Servlet Runner
  • Servlet Runner NT Service (This is not required, but is strongly recommended)

You can also choose to install the following optional features:

• Metering Server
• Security Proxy
  • Security Proxy NT Service

Note: Reflection for the Web 2008 Standard Edition does not include the server proxy server.

Required Port Settings

During installation, you must configure port values for the IIS HTTPS port (and beginning in Reflection for the Web 2008, for the HTTP port also) and for the servlet runner (Tomcat) HTTP and HTTPS ports.

• IIS HTTPS port values:

• Servlet runner port values:

• HTTP servlet runner (Tomcat) port number = 8880.
• HTTPS servlet runner (Tomcat) port number = 8443.

Configuring Your Web Site for Reflection

By default, the Reflection IIS Wizard creates a new virtual directory named Jakarta in the IIS <Default Web Site> location. If you wish to use a web site other than the <Default Web Site>, follow the steps below to create a virtual Jakarta directory. Otherwise, skip to Windows Server 2003 Configuration.

Note: For Reflection integration with IIS, the IIS server must have a site called <Default Web Site> defined, even if you are planning to integrate Reflection with a different site.

Create a Virtual Directory

Follow the steps below to create and configure a virtual directory for your web site.

1. In Windows, start the Internet Information Services (IIS) Manager (from the Administrative Tools menu).
2. Double-click Internet Information Server and then double-click the icon representing your web server. (If you are using Windows Server 2003, you must also double-click the Web Sites folder.)
3. Double-click the <Default Web Site> icon to expand the site.
4. Right-click the Jakarta folder and click Properties.
5. Copy the Local Path, and then click OK.
6. Right-click the icon for your web site, click New > Virtual Directory to start the New Virtual Directory Wizard.
7. When prompted to enter an Alias, enter Jakarta, and then click Next.
8. When prompted to enter the Directory, paste in the path you copied in step 5 and then click Next.
9. To configure access permissions, select the Execute check box. (The default permissions, Read and Run scripts, must also be selected.) Click Next.
10. Click Finish. The Reflection virtual directory now appears in the list of virtual directories for your web site, and is configured for Reflection for the Web.

Authentication Methods

Follow the steps below to set the virtual directories authentication methods for both ISAPI filters in the virtual directory.

Isapi_redirect.dll

1. Select the Jakarta folder.
2. Right-click isapi_redirect.dll and click Properties.
3. On the File Security tab, under 'Authentication and access control' click Edit.
4. Select the "Enable anonymous access" check box.
5. Clear the following check boxes:

• Integrated Windows authentication
• Digest authentication
• Basic authentication
• .NET Passport authentication (if displayed)

6. Click OK.

Isapi_redirect_sec.dll

1. Select the Jakarta folder.
2. Right-click isapi_redirect_sec.dll and click Properties.
3. On the File Security tab, under 'Authentication and access control' click Edit.
4. Select the following check boxes:

• Integrated Windows authentication
• Basic authentication

5. Clear the following check boxes:

• Enable anonymous access
• Digest authentication
• .NET Passport authentication (if displayed)

6. Click OK.

Windows Server 2003 Configuration

If you are not using Windows 2003, skip to Starting the Administrative WebStation.

If you are using Windows Server 2003, you must add the Jakarta Filter to Web Service Extensions and set the status for this extension to Allowed. Follow these steps:

1. Click Start > Administrative Tools > Internet Information Services (IIS) Manager.
2. Double-click server name.
3. Double-click "Web Service Extensions."
4. On the Extended tab, select the link to "Add a new Web Service Extension…"
5. Set the extension name to JakartaFilter.
6. Click Add. Browse to the location of the file isapi_redirect.dll, and select this file. (The default location for this file is C:\Program Files\ReflectionServer\jakarta-tomcat\bin\native.) Click OK.
7. Click Add. Browse to the location of the file isapi_redirect_sec.dll, and select this file. Click OK.
8. Select the "Set extension status to Allowed" check box. Click OK.

Starting the Administrative WebStation

Once the management server is restarted, you should be able to launch the Administrative WebStation in a browser using the URL below; where <protocol> represents the protocol (either HTTP or HTTPS) accepted by IIS to connect to Reflection, and <hostname> represents the host name of your web server computer.

For example, if your web server supports HTTPS:

If your web server does not support HTTPS:

Note the following:

• If you are accessing the Administrative WebStation from the web server machine, you can open the WebStation from Start > Programs > (Attachmate) Reflection for the Web > Administrative WebStation.
• If your IIS web server uses values other than the defaults of 443 for the HTTPS port or 80 for the HTTP port, you must add the port number to the URL after <hostname>, separated by a colon. For example:

• In Reflection for the Web 2008, the shortcut uses HTTP by default.

1. In a text editor, open the file AdministrativeWebStation.html, typically located in \ReflectionServer\utilities.
2. Scroll to the line <meta http-equiv="refresh" content=0; URL=https://[Servername]:[Port#]rweb/AdminStart.html">, change "https" to "http," and, if necessary, edit the line to reflect the correct port number for HTTP. If HTTP is using port 80 (default), you do not need to specify the port number.

• If the Administrative WebStation does not launch, you may want to verify that the ISAPI filter loaded properly:
  • For Windows 2000 server, in your IIS console, right-click the icon for your web server and select Properties. Under Master Properties, WWW Service, select Edit. Click the ISAPI Filters tab.
  • For Windows 2003 server, in your IIS console, right-click the icon for Web Sites and select Properties. Click the ISAPI Filters tab.

• For more information about starting the Administrative WebStation, see the topic titled "Starting the Administrative WebStation" in the Installation Guide.
• If the SSL certificate used by IIS was signed by a Microsoft Certificate Authority, and you are running Sun Java Plug-in version 1.4.2, then the Administrative WebStation will not run. You must run an earlier or later version of the plug-in.

Running the IIS Wizard (if integration was skipped during installation)

If you selected to integrate with IIS during the Reflection installation, skip this section. If you did not select to integrate with IIS during installation, follow the steps below to configure your Reflection installation using the IIS Wizard utility:

Note: For Reflection integration with IIS, the IIS server must have a site called <Default Web Site> defined. For further details, see Prerequisites.

1. Click Start > All Programs (for Windows 2000 Server—Programs) > (Attachmate) Reflection for the Web > Utilities > IIS Wizard.
2. Select the language. Click OK.
3. When prompted to enter the IIS HTTPS port value (and, beginning in Reflection for the Web 2008, the HTTP port value also), enter the port that your IIS web server uses for HTTPS. (By default, the HTTPS port is 443; the HTTP port is 80.) Note the following:

• If you plan to use HTTP instead of HTTPS to access Reflection management server, you must still enter an HTTPS port value on this screen. In this case, enter 443, even if HTTPS is not enabled in your IIS web server.
• To verify the ports used by your IIS web server, right-click your web site in the IIS console, select Properties, and click Advanced on the Web Site tab.

4. After the wizard has completed the configuration, click Finish.
5. Restart both IIS and the Reflection server.

Additional Steps After Running the IIS Wizard

If you are using Windows Server 2003, follow the steps in Windows Server 2003 Configuration to properly add and configure the Jakarta Filter.

If you wish to use a web site other than the <Default Web Site>, follow the steps in Configuring Your Web Site for Reflection.

Unintegrating Tomcat Servlet Runner with IIS

Beginning in Reflection for the Web version 8.0, you can unintegrate Tomcat servlet runner with IIS by running the IIS Wizard. Follow these steps:

1. Click Start > Programs > (Attachmate) Reflection for the Web > Utilities > IIS Wizard.
2. Select the language; click OK.
3. Click Next.
4. On this panel, select Unintegrate and click Next.
5. This panel displays, "Tomcat and IIS have now been unintegrated." Click Finish.

Now, to access Reflection for the Web, use the Tomcat ports assigned during the Reflection for the Web installation.

Where to Go Next

At this point, the procedure for integrating Reflection for the Web's Tomcat servlet runner with IIS is complete. You may want to consult the Reflection for the Web Installation Guide for information about setting up Reflection for the Web's optional security or metering components, or upgrading any existing sessions or settings.

For information about Reflection for the Web's access control options, open the Administrative WebStation. In the left-navigation bar, click Overview, and then click Access Control Overview.

For information about setting up Single Sign-on through IIS authentication with Reflection for the Web, see on-line help under Access Control setup in the Administrative WebStation.

For a full list of Reflection for the Web information resources, see Technical Note 1668.

Related Technical Notes

1668	Reflection for the Web Information Resources
9988	Reflection for the Web Technical Notes