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:
- IIS 8.0 is installed and running
- 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
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:
- 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.
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:
Then add the following lines:
Save and close the file.
After the update, the file should look like 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.
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.
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.
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.
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.
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.
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.
- 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.
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.
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.
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.
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.
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.
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.
LDAP integration process must be completed.
For LDAP, integration information can be found here:
For LDAPS, integration information can be found here:
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.
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.
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.
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:
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.
Trouble Shooting issues:
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. The probable causes for this error are the following: Note: The error page may suggest to enable directory browsing, this can safely be disregarded.
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.
The probable causes for this error are the following:
Note: The error page may suggest to enable directory browsing, this can safely be disregarded.