Attachmate Worldwide  |   Contact Us  |   The Attachmate Group
Extend. Manage. Secure. More than 30 years in the business. Over 65,000 customers.

Technical Notes

Integrating Reflection for the Web with IIS 5.x or 6.0
Technical Note 2195
Last Reviewed 02-Jun-2011
Applies To
Reflection for the Web 2008 (All Editions)
Microsoft Windows Server 2003
Microsoft Internet Information Server (IIS) version 5.0 through 6.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. This technical note assumes that IIS has already been installed on your server.

A utility is available to integrate specific versions Reflection for the Web with IIS, as follows.

  • Reflection for the Web 2011 includes a utility to integrate Reflection for the Web with IIS 6.x or 7.x. To locate and run the IIS 7 utility, follow the instructions in the Installation Guide, http://docs.attachmate.com/reflection/rweb/2011/R1/rweb_installguide_en.pdf. (Go to the topic, Running the IIS Integration Utility.)
  • If you are running Reflection for the Web 2008 on Windows Server 2008, and want to integrate with IIS 7.x, see Technical Note 2543. For earlier versions, continue with the information in this technical note.

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.

By default, the IIS ports are: HTTP = 80 and HTTPS = 443.

  • 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 removed the <Default Web Site> from IIS, you must redefine a site with this name before proceeding.

If no <Default Web Site> is found, the installation will hang and the following error will display in the IISWizard log:

CreateVirtualRoot: Error - 2147024892 (0x80070003) creating key for virtual root
  • You must be logged in as a user with administrative privileges.

Before You Begin: Information to Review

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

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. In 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.

If all three buttons in the Secure communications area are enabled, then HTTPS support is enabled in your web server. Skip to the next section, Installing Reflection for the Web.

If the View Certificate or Edit buttons appear dimmed, HTTPS is not yet enabled. You must follow one of the two options below.

Option 1 (Recommended): Enable HTTPS support in IIS.

Follow these steps to request and incorporate a web server certificate from a Certificate Authority (CA) in order to enable HTTPS support in IIS.

    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.

When completed, HTTPS support is enabled in IIS. All three buttons in the Secure communications area should appear enabled.

If you want to require HTTPS, follow the steps below to configure Reflection for HTTPS.

    1. Start the Administrative WebStation and log in 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.

In Reflection for the Web 9.x, under "Choose management server access protocol," select HTTPS, and then click Save Settings at the top or bottom of the Reflection Settings page.

Option 2 (Not Recommended): Use HTTP to access sessions on the Reflection management server.

Reflection for the Web defaults to allowing HTTP; however, this option is not recommended because HTTP does not encrypt communications sent between client computers and Reflection management server (including user names and passwords).

If you choose to use HTTP, no changes are necessary.

Installing Reflection for the Web

To integrate Reflection with IIS, you must use the Reflection automated installer to install Reflection onto your Microsoft Windows Server 2003 web 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:

For the IIS HTTPS (and HTTP in Reflection for the Web 2008) port value enter the port that your IIS web server uses for HTTPS (and HTTP).

By default, the IIS ports are: HTTP = 80 and HTTPS = 443.

  • Servlet runner port values:

The default Servlet Runner Port values used by the Reflection (Tomcat) servlet runner are:

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

If necessary, change the default values to an unused port number.

In earlier versions, while running the installation wizard, you must change the servlet runner port settings from their default values in order to avoid conflicts with IIS during configuration.

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)
  1. 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
  1. Clear the following check boxes:
    • Enable anonymous access
    • Digest authentication
    • .NET Passport authentication (if displayed)
  1. 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.

<protocol>://<hostname>/rweb/AdminStart.html

For example, if your web server supports HTTPS:

https://mywebserver/rweb/AdminStart.html

If your web server does not support HTTPS:

http://mywebserver/rweb/AdminStart.html

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:
https://mywebserver:444/rweb/AdminStart.html

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.

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

In Reflection for the Web 8.0 – 9.x, if IIS is configured for HTTPS, the shortcut's target URL is automatically updated when the IIS Wizard is run. However, if you are using HTTP because HTTPS is not available, follow the steps below to modify the URL to use HTTP.

    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:

In your IIS console, right-click the icon for Web Sites and select Properties. Click the ISAPI Filters tab.

You should see two ISAPI filters, JakartaFilter and JakartaFilter_Sec. There should be a green up-arrow by each filter name, indicating that the filter is loaded. If the filters are not loaded, select each filter and click Enable.

  • 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 > (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.
  1. After the wizard has completed the configuration, click Finish.
  2. Restart both IIS and the Reflection server.

To restart the Reflection server if you installed it as an NT service, go to Control Panel > Services, and then right-click Reflection Server. If you did not install it as a service, go to Start > Programs > (Attachmate) Reflection for the Web, click Stop Servlet Runner, and then Start Servlet Runner.

For information about restarting IIS, see your Microsoft IIS product documentation.

Alternatively, you can reboot your system to restart 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 from IIS

You can unintegrate Tomcat servlet runner from 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.

Next Steps

At this point, the integration of Reflection for the Web's Tomcat servlet runner with IIS is complete. 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 online help under Access Control setup in the Administrative WebStation.

Related Technical Notes
2543 Integrating Reflection for the Web with IIS 7.x on Microsoft Windows
9988 Reflection for the Web Technical Notes

horizontal line

Did this technical note answer your question?

           


Need further help? For technical support, please contact Support.