Tomcat: IIS Integration – OSKAR

This requires editing server.xml on your server in the server configuration (Server/conf) directory and Admin Privileges.

Normally IIS cannot execute Servlets and Java Server Pages (JSPs), configuring IIS to use the Tomcat JK ISAPI redirector will let IIS send to and from requests to Tomcat. To add an extra layer of security Tomcat hosting iDashboards can be deployed behind Microsoft IIS. In such deployment, iDashboards browser requests are sent to the webserver, rather than directly to Tomcat. The webserver then transmits the requested data to Tomcat (via ISAPI), which invokes the appropriate iDashboards servlet, and the iDashboards response data is sent by Tomcat back to the webserver. Running iDashboards with IIS in this methodology will lead to allowing Single Sign-On (SSO) through your Microsoft Active Directory if enabled. Application Server Based SSO (optional) details how to accomplish SSO.

Before you Start - Install Tomcat - Configuring Tomcat

Install and Configure IIS - Connecting IIS with Tomcat - Setup ISAPI & CGI Restrictions

Enable ISAPI Filters - Creating Jakarta Virtual Directory - Creating iDashboards Directory

iDashboards Windows Authentication - Jakarta Windows Authentication - Enable the ISAPI Handler

Test and Run - Application Server Based SSO (optional) - Errors

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 (32-bit)
- tomcat-connectors-1.2.37-windows-x86_64-iis.zip (64-bit)
- Isapi_redirect.dll
Java JDK/JRE should be installed and running
Tomcat should be installed and running
Active Directory installed and working

Install Tomcat

Install Tomcat with default settings and test running the URL example: http://localhost:8080 as shown:

Tomcat 9: How to Install on Ubuntu 18.04

Configuring Tomcat

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.

Under the iDashboards_SRV directory create the following folder: ISAPI
Copy the isapi_redirect-2.37.dll file into the ISAPI folder
Then rename the file to isapi_redirect.dll
Copy isapi_redirect.properties into the 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:

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 which is often the following: C:\Program Files\iDashboards_SRV\server

C:\Program Files\iDashboards_SRV\server\conf\uriworkermap.properties
C:\Program Files\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:

You can also copy/create the sample workers.properties file from the download as shown below and save it to the following location: C:\Program Files\iDashboards_SRV\server\conf

Open the workers.properties file in a text editor and locate the following lines:

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 the file, then close it.

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

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

Remove the following: redirectPort="8443"

Add the following: tomcatAuthentication="true"

After the update:

Before you Start - Configuring Tomcat

Install and Configure IIS

Now we need to configure IIS. Test by starting IIS and opening your browser to http://localhost.

You should see an image similar to the following:

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: Start ->in the search type: CompMgmtLauncher.exe from there click Roles, in Role Services click Add Role Services this will take you to the Role Wizard.

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

Click Next and Finish.

Install and Configure IIS - Connecting IIS with Tomcat

Setup ISAPI & CGI Restrictions

Connecting IIS with Tomcat

To connect IIS to the Tomcat server we are going to leverage a Microsoft 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 Start -> Run -> inetmgr.exe

This brings up the IIS Management Console. You can also launch this by: Start -> right click on the Computer -> Manager -> Expand Services and Applications -> IIS Manager

Connecting IIS with Tomcat - Setup ISAPI & CGI Restrictions

Enable ISAPI Filters

Setup ISAPI & CGI Restrictions

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

For ISAPI or CGI Path click the … and choose your isapi_redirect.dll file at your tomcat installation folder: C:\Program Files\iDashboards_SRV\Server\ISAPI

In the description type Tomcat-ISAPI.DLL
Check Allow extension path to execute and click OK
Setup ISAPI & CGI Restrictions- Enable ISAPI Filters

Creating Jakarta Virtual Directory

Enable ISAPI Filters

Select Default Website and double click ISAPI Filters to open it, then click Add

Enter Jakarta in the Filter Name and navigate ISAPI directory

Click Open and in the following location:

C:\Program Files\iDashboards_SRV\Server\ISAPI\isapi_redirect.dll

Select isapi_redirect.dll and click OK to close the window

Enable ISAPI Filters - Creating Jakarta Virtual Directory

Creating iDashboards Directory

Creating Jakarta Virtual Directory

Expand the server node, right click on the website and create a virtual directory

Give it an alias of jakarta and a Physical path of: C:\Program Files\iDashboards_SRV\Server\ISAPI

Incidentally, you do not have to call the virtual directory jakarta - you can actually give it any name you want, 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, however in IIS 7.5:

In the left side pane select the Jakarta virtual directory and then double-click Handler Mappings
Once you are in Handler Mappings right click on the ISAPI.dll and select Edit feature permissions. In Feature Permission from the Actions bar, Check All (Read, Script, and Execute) then click OK

With this the installation of the Tomcat Connector is now complete.

Creating Jakarta Virtual Directory - Creating iDashboards Directory

iDashboards Windows Authentication

Creating iDashboards Directory

Now we need to add our iDashboards Application Directory to run within IIS.

Add idashboards

Right click on the website node and select Add Application
Type in the site name: idashboards
Select idashboards web application folder
Click OK to add idashboards in the application directory

Add idbdata

Right click on the website node and select Add Application
Type in the site name: idbdata
Select idbdata web application folder
Click OK to add idbdata in the application directory

Creating iDashboards Directory - iDashboards Windows Authentication

Jakarta Windows Authentication

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

iDashboards Windows Authentication - Jakarta Windows Authentication

Enable the ISAPI Handler

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

Jakarta Windows Authentication - Enable the ISAPI Handler

Test and Run

Enable the ISAPI Handler

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

Click Start -> type in: CMD
Right-click on cmd.exe and click Run as Administrator
In the command prompt type: iisreset
Press Enter

Enable the ISAPI Handler - Test and Run

Application Server Based SSO (optional)

Test and Run

Now from the server you should be able to access the iDashboards login page from:

http://localhost/idashboards

Test and Run

Application Server Based SSO (optional)

Errors

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. One of the following must be completed:

LDAP Integration OR LDAPS Integration

The first step in configuration is placing the NTLMAuth.dll file (attached) in the following location:

C:\Windows\System32

Once this file has been placed in the directory above, we will go back to the following and open: C:\Program Files\iDashboards_SRV\Server\conf\server.xml

and locate the following:

and change it to:

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

tomcatAuthentication=false

After the update:

Next we need to log into iDashboards Admin to enable the Appserver-Based Single SignOn

Once logged on click: System -> Authentication -> Appserver-Based Single Sign-On

Here we will set the first option Appserver-Based Single Sign-on Enabled TRUE

The second option will vary: Appserver Username Starting Delimiter are used to remove static portions of the authentication information that is part of the username

In our 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 use Single Sign-On in iDashboards you would use the following URL:

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.

Enable the ISAPI Handler

Test and Run - Application Server Based SSO (optional)

Errors

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:

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

Cause

The probable causes for this error are the following:

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.
Windows Process Activation Service is not enabled.

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

Action

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 can be found under Advanced in the defaultApplication pool
3. Recreate the ISAPI module starting in: Setup ISAPI & CGI Restrictions . If you no longer get an error, this means you were using the 64-bit ISAPI Redirect DLL.
If the error still exists, enable Windows Process Activation Service and all its sub processes in: Turn Windows features on or off