action.skip

Integrate MSS with IIS for IIS Single Sign-On

This section describes how to integrate MSS with IIS, for the purpose of using IIS Single Sign-On.

Note

When integrated with IIS, a common/shared certificate and private key is used to provide security (HTTPS) for the Cluster DNS entrypoint and IIS.

Refer to the Microsoft IIS documentation for instructions on how to install IIS and its features.

Requirements

  • IIS 8.0 or higher
  • IIS features that must be enabled:
    • ISAPI Extensions
    • ISAPI Filters
    • Windows authentication
  • A common/shared certificate and private key pair that will be used by both the Cluster DNS entrypoint and the IIS website.
  • Check your firewall settings to ensure that requests from the IIS server to the cluster's AJP port are allowed (default is 8001).
  • DNS resolution must be working properly between IIS and the Cluster DNS name for transparent Single Sign-On to succeed.

IIS integration steps

Download and install the ISAPI redirector

  1. Download the ISAPI redirector DLL from the Apache Tomcat website at https://dlcdn.apache.org/tomcat/tomcat-connectors/jk/binaries/windows/

  2. Select the ZIP file for x86-64, unless a different platform is required.

  3. On the machine where IIS is installed, create a directory that will be used to contain the redirector files.

  4. Unzip the redirector files into the directory.

  5. Create a copy of the file named isapi_redirect.dll. Rename the copied file to isapi_redirect_sec.dll.

Create a configuration file for the redirector

  1. In the same directory, create a file named isapi_redirect.properties.

  2. Copy this content to the file: 

    worker_file=workers.properties
worker_mount_file=uriworkermap.properties
log_level=emerg
log_file=iis_redirect.log
extension_uri=/tomcat/isapi_redirect.dll

Create a configuration file for the second redirector

  1. In the same directory, create a file named isapi_redirect_sec.properties.

  2. Copy this content to the file: 

    worker_file=workers.properties
worker_mount_file=uriworkermap_sec.properties
log_level=emerg
log_file=iis_redirect_sec.log
extension_uri=/tomcat/isapi_redirect_sec.dll

Create a worker file for the redirector

  1. In the same directory, create a file named workers.properties.

  2. Copy this content to the file: 

    ps=\
worker.list=ajp13_worker
worker.ajp13_worker.port=8001
worker.ajp13_worker.host=
worker.ajp13_worker.type=ajp13
worker.ajp13_worker.secret=changeit
worker.ajp13_worker.lbfactor=1
worker.loadbalancer.type=lb
worker.loadbalancer.balanced_workers=ajp13_worker

  3. Specify the cluster DNS name as the value for the property named worker.ajp13_worker.host.

Create a URI mapping file for the first redirector

  1. In the same directory, create a file named uriworkermap.properties.

  2. Copy this content to the file: 

    default.worker=ajp13_worker
/mss|/*=$(default.worker)
/tidm|/*=$(default.worker)
/adminconsole|/*=$(default.worker)
!/adminconsole/plugins|/*=$(default.worker)
/login|/*=$(default.worker)
/sessions|/*=$(default.worker)

Create a URI mapping file for the second redirector

  1. In the same directory, create a file named uriworkermap_sec.properties.

  2. Copy this content to the file: 

    default.worker=ajp13_worker
/iisred|/*=$(default.worker)

Add the virtual directory to IIS

  1. Open the IIS Manager application.

  2. In the Connections pane, expand the tree to view the website to integrate.

  3. Right-click the website to integrate, and click Add Virtual Directory...

  4. Specify an Alias value of tomcat.

  5. For the Physical path value, browse to the directory that contains the ISAPI redirector DLL files.

  6. Click OK to close the dialog.

  7. In the Connections pane, right-click the tomcat virtual directory, and select Edit Permissions...

  8. Click the Security tab, Edit..., and then click Add...

  9. In the Enter the object names to select box, add the following local Groups:

    • IUSR
    • IIS_IUSRS

    Click OK to close each dialog in succession.

Enable execution of IIS Handler Mappings

In the IIS Manager application:

  1. In the Connections pane, select the tomcat virtual directory.

  2. In the tomcat Home view, double-click Handler Mappings.

  3. In the Actions view, click Edit Feature Permissions...

  4. Select the Execute checkbox and then OK.

Configure Windows authentication for the second ISAPI redirector

In the IIS Manager application:

  1. In the Connections pane, right-click the tomcat virtual directory and select Switch to Content View.

  2. In the tomcat Content view, right-click isapi_redirect_sec.dll and select Switch to Features View.

  3. In the isapi_redirect_sec.dll Home view, double-click Authentication.

  4. Disable Anonymous Authentication.

  5. Enable Windows Authentication.

Configure the ISAPI Filters for the website

In the IIS Manager application:

  1. In the Connections pane, under the Sites node, click the website to integrate.

  2. In the website's Home view, double-click ISAPI Filters.

  3. In the Actions pane, click Add..., and specify the following values:

    • Name: isapi_redirect
    • Executable: Browse and select the file named isapi_redirect.dll

    Click OK to close the dialog.

  4. In the Actions pane, click Add..., and specify the following values:

    • Name: isapi_redirect_sec
    • Executable: Browse and select the file named isapi_redirect_sec.dll

    Click OK to close the dialog.

  5. In the Actions pane, click View Ordered List...

  6. Ensure that isapi_redirect is at the top of the list, and that isapi_redirect_sec is second in the list.

Enable ISAPI extensions for IIS

In the IIS Manager application:

  1. In the Connections pane, select the top-most node, for the IIS server.

  2. In the server's Home page, double-click ISAPI and CGI Restrictions.

  3. Add the isapi_redirect.dll and isapi_redirect_sec.dll files, and for each select the checkbox to Allow extension path to execute.

  4. Restart IIS.

Important

Integration is not complete. The MSS Admin Console plug-ins and products will not work until an IIS Reverse Proxy is added -- the next step.

Next Step: Configure the IIS Reverse Proxy

Next, configure the IIS Reverse Proxy for products and MSS Admin Console plug-ins.

Troubleshooting

  • Ensure firewalls are not interfering with connections between IIS and MSS.
  • You may need to restart IIS or redeploy MSS.
  • Ensure the user is authenticated with IIS, prior to accessing MSS or any other applications.
  • Inspect the IIS logs and Windows Event logs for any information regarding issues.
  • Enable logging for the Tomcat ISAPI redirector and inspect the logs.
  • If an HTTP 500 error is encountered, launch a browser from the IIS host to obtain richer information from IIS about the failure.