Objective: Configure IIS integration with Tomcat

Normally IIS cannot execute Servlets and Java Server Pages (JSPs), configuring IIS to use the Tomcat JK ISAPI redirector plugin will let IIS send to and from requests to Tomcat. In order to add an extra layer of security Tomcat hosting iDashboards can be deployed behind Microsoft IIS. In such a deployment scenario, iDashboards browser requests are sent to the webserver, rather than directly to Tomcat. The webserver then transmits the requested data to Tomcat (via ISAPI plugin), which invokes the appropriate iDashboards servlet, and the iDashboards response data is sent by Tomcat back to the webserver. This document explains how to set up IIS to cooperate with Tomcat Prerequisites.

Running iDashboards with IIS as a front end in this methodology will lead to allowing Single Sign-On (SSO) through your Microsoft Active Directory only if enabled.  The last section, ‘Application Server Based SSO (optional)’, details how to accomplish SSO.

Check Before you start:

Make sure of the following:

1. IIS 8.0 is installed and running
2. Connector Package for IIS is installed (pre installed with installer, or available below)
• tomcat-connectors-1.2.37-windows-i386-iis.zip  32bit Windows
• tomcat-connectors-1.2.37-windows-x86_64-iis.zip 64bit Windows
• Isapi_redirect.dll
3. Java JDK/JRE should be installed and running.
4. Tomcat should be installed and running.
5. Active Directory installed and working.

Install Tomcat 

Install Tomcat with default settings and test running the URL example: http://localhost:6700 as shown in Figure 1.

Configuring Tomcat using ISAPI dll

Now that all the prerequisites are installed, it is time to begin the actual integration between IIS and Tomcat. This process can be broken down into two sections: configuring Tomcat and configuring IIS.

We need to configure the ‘JK 1.2.x Connector’ which will allow IIS to effectively act as a proxy and forward requests on to Tomcat. You can download the software used in this document here:

http://www.apache.org/dist/tomcat/tomcat-connectors/jk/#binaries

• Create a folder called ‘ISAPI’ under the iDashboards server directory.
• Copy the isapi_redirect-2.37.dll file into the ‘ISAPI’ folder and rename the file to isapi_redirect.dll as shown in Figure 2
• Copy isapi_redirect.properties file into the same ISAPI folder.

The isapi_redirect.properties file tells the connector where to find its configuration files and where the isapi_redirect DLL file is located. If you have used the same directory structure as shown, you can configure your isapi_redirect.properties file as shown in Figure 3.

Figure 2

Figure 3

We need to either update or create the two Tomcat connector configuration files so that the connector knows how to handle the requests it receives. Copy/create the sample uriworkermap.properties file. Both config files need to be placed in the ‘<Tomcat home directory>\conf’ folder which in this example is ‘C:\Program Files (x86)\iDashboards_SRV\server‘.

• C:\Program Files (x86)\iDashboards_SRV\server\conf\uriworkermap.properties
• C:\Program Files (x86)\iDashboards_SRV\server \conf\workers.properties

 

Open ‘uriworkermap.properties’ file in a text editor and comment the following lines:

#/admin/*=wlb

#/manager/*=wlb

#/jsp-examples/*=wlb

#/servlets-examples/*=wlb

#/jkmanager=jkstatus

 

 

Then add the following lines:

/idashboards/*=wlb

/idashboards=wlb

 

/idbdata/*=wlb

/idbdata=wlb

 

Save and close the file.

After the update, the file should look like Figure 4.

Figure 4

You can also copy/create the sample ‘workers.properties’ file from the download as shown below and save it to the ‘C:\Program Files (x86)\iDashboards_SRV\server\conf’ folder. Open ‘workers.properties’ file in a text editor and locate the following lines as shown in Figure 5.

worker.ajp13w.host=localhost

worker.ajp13w.port=8009

 

If Tomcat and IIS are running on different servers then change “localhost” to the name of the server where Tomcat is running. The port number ‘8009’ defined in this file should match with the one configured for the AJP 1.3 Connector defined in ‘<TOMCAT HOME>\conf\server.xml’.

 

Save and close the file.

Figure 5

Open C:\Program Files (x86)\iDashboards_SRV\Server\conf\server.xml file and locate these lines:

<Connector port="8009" enableLookups="false" redirectPort="8443" protocol="AJP/1.3" />.

Remove the attribute ‘redirectPort="8443"’, and add an attribute ‘tomcatAuthentication="true"’. After the update, the file should look like Figure 6.

Figure 6

Install and Configure IIS Role

Now we need to configure IIS. Test the IIS installation, by starting IIS and opening your browser to http://localhost.  You should see an image similar to the following to Figure 7.

Figure 7

Add IIS Roles

Now in order for the user name to be passed to iDashboards you must add ‘Windows Authentication’ in the Web Server (IIS) role. 

You can add the role by clicking ‘Start’ -> type in ‘CompMgmtLauncher.exe’ from the window click on ‘Roles’ in the ‘Role Services’ section click ‘Add Role Services’ this will take you to the ‘Role Wizard’.

Needed Roles are:

• Application Development: CGI, ISAPI Extentions, ISAPI Filters, Server Side Includes
• Security: Windows Authentication, Request Filtering
• Performance: Static Content Compression, Dynamic Content Compression

Shown in Figure 8.

Figure 8

Click next and finish the installation. 

Connecting IIS with Tomcat

To connect IIS to the Tomcat server, we are going to leverage a Microsoft technology called ISAPI. We do not need to know much about this technology; we simply need to make use of an existing Dynamic Link Library (DLL) that has already been built.

Click on ‘Start’ -> ‘Run’ -> 'inetmgr.exe'.

This brings up the IIS Management Console. You can also launch this dialog by going to ‘Start’ -> <right click on the Computer> -> select ‘Manager’ -> Expand ‘Services and Applications’ -> select ‘IIS Manager’.

Setup ISAPI & CGI Restriction at IIS Server

With IIS manager open select your server

From this feature view open ‘ISAPI and CGI Restrictions’, right-click in the open area and select ‘Add’ as shown in Figure 9.

Figure 9

For ‘ISAPI or CGI Path’ click the … Button and choose your isapi_redirect.dll file at your tomcat installation folder (C:\Program Files (x86)\iDashboards_SRV\Server\ISAPI\) as shown in Figure 10.

Figure 10

• In the description field, type ‘Tomcat-ISAPI DLL’.
• Check the ‘Allow extension path to execute’ and click OK.

Enable ISAPI filters at IIS default website

Select ‘Default Website’ and double click ‘ISAPI Filters’ to open it and click ‘Add’ as shown in Figure 11.

Figure 11

Enter “Jakarta” in the ‘Filter Name’ and navigate ISAPI directory. Click open and select the isapi_redirect.dll (C:\Program Files (x86)\iDashboards_SRV\Server\ISAPI\isapi_redirect.dll) press ‘OK’ to close the window as shown in Figure 12.

Figure 12

Creating the Jakarta Virtual Directory 

Expand the server node.  Right click on the Web site and create a virtual directory.  Give it an alias of ‘jakarta’ and a Physical path of ‘C:\Program Files (x86)\iDashboards_SRV\Server\ISAPI’ as shown in Figure 13.

Figure 13

Incidentally, you don’t have to call the virtual directory ‘jakarta’ - you can actually give it any name you like, just so long as the name you choose appears in the extension_uri line of your

‘isapi_redirect.properties’ file.  Next we need to configure the Jakarta directory to have ‘execute’ permission. This was a simple check box option in IIS 6.0 but in IIS 7.5:

• Select the Jakarta virtual directory in the left side pane and then double-click ‘Handler Mappings’ are in the right side pane as shown in Figure 14.
• Once you are in the handler mapping pane right click on the ISAPI-dll and then select Edit feature permissions.
• From Feature Permission from the Actions bar and Check All (Read, Script, and Execute) and click ‘OK’ as shown in Figure 15.

Figure 14

Figure 15

iDashboards Application Directory

With this, the installation of the Tomcat Connector is now complete. Now we need to add our iDashboards application directory to run within IIS. To do this:

• Add idashboards.
• Right click on the web site node and select ‘Add Application’.
• Type in the site name as ‘idashboards’.
• Select the ‘idashboards’ web application folder.
• Click ‘OK’ to add idashboards application directory.
• Add idbdata
• Right click on the web site node and select ‘Add Application’.
• Type in the site name as ‘idbdata’.
• Select the ‘idbdata’ web application folder.
• Click ‘OK’ to add idbdata application directory.

An example of one of these is shown in Figure 16.

Figure 16

iDashboards Windows Authentication

Clicking on iDashboards directory in the IIS Manager you will see the option for ‘Authentication’. 

Double click on ‘Authentication and disable Anonymous’ and enable ‘Windows Authentication’.

Jakarta Windows Authentication

Clicking on Jakarta directory in the IIS Manager you will see the option for ‘Authentication’.

Double click on ‘Authentication’ and disable ‘Anonymous’ and enable ‘Windows Authentication’.

Enabled the ISAPI Handler for the iDashboards Application

Now restart IIS following the below steps to reflect the changes you made in the IIS console.

• Click on ‘Start’ -> type ‘CMD’. Right-click on cmd.exe and click on “Run as Administrator”.
• At the command prompt type ‘iisreset’ and press enter as shown in Figure 17.

Figure 17

Test and Run

Now from the server you should be able to access the iDashboards login page from http://localhost/idashboards.

Application Server Based SSO (optional)

iDashboards supports Application server based Single Sign-On in a variety of configurations, one of the more common using Microsoft’s Active Directory to bypass the traditional login prompt and instead authenticate a user against iDashboards based on their authentication to the domain. In order to properly configure this functionality not only does the IIS-Tomcat integration need to be complete, LDAP integration with Active Directory must also have been completed as well. Because IIS websites support Windows Authentication, iDashboards is able to extract a user’s credentials and use them for authentication allowing users to bypass the traditional login screen. This section explains how to set up application server based Single Sign-On.

 

Prerequisites:

 

LDAP integration process must be completed.

For LDAP, integration information can be found here:

LDAP-Integration 

For LDAPS, integration information can be found here:

LDAPS Integration

 

Configuring Application Server Based SSO:

The first step in configuring application server based SSO is placing the NTLMAuth.dll(available below) file in the ‘C:\Windows\System32’ directory as shown in Figure 18.

Figure 18

Once this file has been placed in the directory above, the next step will be to go back, open ‘C:\Program Files (x86)\iDashboards_SRV\Server\conf\server.xml’ file, and locate the following line:

<Connector port="8009" enableLookups="false" protocol="AJP/1.3" tomcatAuthentication="true"/>

and change it to:

<Connector port="8009" enableLookups="false" protocol="AJP/1.3" tomcatAuthentication="false"/>

To enable the actual mechanism for authentication we will need to change the

‘tomcatAuthentication’ attribute setting it equal to ‘false’. After the update the file should look like the example as shown in Figure 19.

Figure 19

Next we need to log into the iDashboards Admin application to enable the Appserver-Based Single SignOn. Once logged in click ‘System’>’System Settings’>’Appserver-Based Single Sign-On’.

Here we will set the first option server-Based Single Sign-on Enabled equal to ‘TRUE’. The second options will vary from installation to installation; the starting and ending delimiter are used to remove static portions of the authentication information that is part of the username as shown in Figure 20.

In our example installation, the logon criteria supplied to iDashboards is TestDomain\username. To successfully authenticate, iDashboards needs to have only the username from the username string extracted; using the starting delimiter static criteria such as TestDomain\ can be removed from that string leaving only the username, in the case of additional static information appearing after the username the ending delimiter would be used in the same fashion.

Figure 20

Once all of the above steps have been completed successfully, it is time to test the Single Sign-On authentication mechanism. To invoke Single Sign-On in iDashboards use the following URL to login:

http://<sesrver address>/idashboards/?sso=$|auth=container

If the integration has completed successfully you should be logged in as the user you have logged into your computer as and not see a login prompt as shown in Figure 21.

Figure 21

 

Trouble Shooting issues:

 

 

 

 

 

 

 

 

403.14-Forbidden error

After starting the application server and IIS, accessing any Appian URL that contains "/idashboards" will result in the following 403.14-Forbidden error screen:

Accessing the the root domain will successfully load the IIS screen, and iDashboards can be reached from Tomcat.

Cause

The probable causes for this error are the following:

1. The ISAPI module (isapi_redirect.dll) is failing to properly load. This happens when IIS was set up with a specific version of the module, either 32-bit or 64-bit, and was later modified.
2. Windows Process Activation Service is not enabled.

Note: The error page may suggest to enable directory browsing, this can safely be disregarded.

Action

1. It is possible that the incorrect ISAPI Redirector DLL is being referenced and the ISAPI module may need to be reconfigured. To reconfigure the ISAPI module, perform the following:
   1. Delete the ISAPI module set up in step Set Up IIS documentation.
   2. Once deleted, change the setting ‘Enable 32-Bit Applications’ to ‘False’ this is found the the defaultApplication Pool under Advanced.
   3. Recreate the ISAPI module from step 12 of the Set Up IIS documentation. If you no longer get an error, this means you were using the 64-bit ISAPI Redirector DLL.
2. If the error still exists, enable Windows Process Activation Service and all its sub processes in "Turn Windows features on or off".