Skip to content

Setup IIS for Easit GO

This guide is an adaptation of the ISAPI redirector for Micrsoft IIS HowTo and is customized for use with Easit GO 2024.06 and later releases. The guide will help you setup a site in IIS for Easit GO, configure ISAPI redirector plugin and enable the AJP connector for Easit GO.

You can have multiple sites and application pool for the same Easit GO enabling you to have one site that authenticates all request against your AD and one that does not.

If you you already have an site, application pool and ISAPI redirector plugin configured you can duplicate and rename the already existing directories and files instead of downloading and re-creating from scratch.

Directories setup

Relative to Easit root directory, often D:\Easit or E:\Easit, we need to create 2 directories.

  • ISAPI
  • wwwRoot

Directory structure should look like this:

  • D:
    • Easit
      • ISAPI
      • wwwroot

Inside each directory, create a directory with the site name you would like to use for the Easit GO application. Below you can find some suggestions for this:

Service name Application root Site name ISAPI root wwwRoot
EasitGO-Prod D:\Easit\EasitGOProd EasitGO-Prod D:\Easit\ISAPI\EasitGOProd D:\Easit\wwwroot\EasitGOProd
EasitGO-Test D:\Easit\EasitGOTest EasitGO-Test D:\Easit\ISAPI\EasitGOTest D:\Easit\wwwroot\EasitGOTest
ConnectorName-Prod D:\Easit\ConnectorNameProd ConnectorName-Prod D:\Easit\ISAPI\ConnectorNameProd D:\Easit\wwwroot\ConnectorNameProd
ConnectorName-Test D:\Easit\ConnectorNameTest ConnectorName-Test D:\Easit\ISAPI\ConnectorNameTest D:\Easit\wwwroot\ConnectorNameTest

Using the table of suggestions the directory structure would look like this:

  • D:
    • Easit
      • ISAPI
        • Site name
      • wwwroot
        • Site name

Configure ISAPI redirector plugin

Since IIS normally can not execute Servlets and Java Server Pages (JSPs), it needs to be configuring to use the ISAPI redirector plugin and that will let IIS send servlet and JSP requests to Tomcat (and this way, serve them to clients).

Create the following directories inside ISAPI root:

  • bin
  • conf
  • logs

Download the the plugin from the Tomcat Connectors archive and copy the contents of the archive tomcat-connectors-x.x.x-windows-x86_64-iis.zip to the ISAPI root. Then move the isapi_redirect.dll to the bin directory.

Inside the bin directory, create a file named isapi_redirect.properties (make sure it does not end with .txt). Edit isapi_redirect.properties and add the following content.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
# Configuration file for the Jakarta ISAPI Redirector

# The path to the ISAPI Redirector Extension, relative to the website
# This must be in a virtual directory with execute privileges
extension_uri=/jakarta/isapi_redirect.dll

# Log level (debug, info, warn, error or trace)
log_level=warn

# Rotate the log file every day
log_rotationtime=86400

# Full path to the log file for the ISAPI Redirector
log_file=$(JKISAPI_PATH)\logs\isapi_redirect.%Y%m%d.log

# Full path to the workers.properties file
worker_file=$(JKISAPI_PATH)\conf\workers.properties

# Full path to the uriworkermap.properties file
worker_mount_file=$(JKISAPI_PATH)\conf\uriworkermap.properties

Save the changes and close the file. More details about the configuration file can be found under Using a properties file for configuration in the Configuring the ISAPI redirector for Microsoft IIS reference.

Now we go to the conf directory inside the ISAPI root and create the following files, again making sure it does not end with .txt.

  • uriworkermap.properties
  • workers.properties

The uriworkermap.properties maps URL-Path patterns to workers. Edit it and add the following content.

1
2
3
4
5
# This file provides sample mappings for the example
# worker "EasitGO-Prod" defined in workermap.properties.
# The general syntax for this file is:
# [URL]=[Worker name]
/*=EasitGO-Prod
Save the changes and close the file. More information about uriworkermap.properties.

The file workers.properties describes the host(s) and port(s) used by the workers (Tomcat processes). Edit it and add the following content.

You will need to set the .secret to some value that you choose. We suggest using a generated string of 12 or more "word" characters (a-z and 0-9) mixing upper and lower cases.

The .port is NOT the port that Easit GO is listen on but rather the AJP connector port that we will configure later in this guide. Feel free to change it if needed.

1
2
3
4
5
6
7
8
# Define a status worker:
worker.list = EasitGO-Prod

worker.EasitGO-Prod.type = ajp13
worker.EasitGO-Prod.host = localhost
worker.EasitGO-Prod.port = 8009
worker.EasitGO-Prod.secret=
worker.EasitGO-Prod.max_packet_size = 32768
Save the changes and close the file. More information about workers.properties.

Configure AJP Connector

Depending on if you are using a release of Easit GO earlier than 2024.06 or not you will be doing this changes either in server.xml (Easit GO 2023.11 and earlier) or properties.xml (2024.06 and later).

  • In the case of Easit GO 2024.06 we add the following keys to properties.xml which can be found in the [ApplicationRoot]\config directory.
  • In the case of Easit GO 2023.11 we uncomment the AJP connector in server.xml which can be found in the [ApplicationRoot]\tomcat\conf directory.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
    <!-- Settings for AJP-connector used by ISAPI filter in IIS site -->
    <entry key="ajp.enabled">true</entry>
    <entry key="ajp.address">127.0.0.1</entry>
    <entry key="ajp.port">8009</entry>
    <entry key="ajp.redirectPort">8443</entry>
    <entry key="ajp.tomcatAuthentication">false</entry>
    <entry key="ajp.packetSize">32768</entry>
    <entry key="ajp.allowedRequestAttributesPattern">.*</entry>
    <entry key="ajp.secret"></entry>
</properties>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
<?xml version="1.0" encoding="UTF-8"?>
<Server port="-1" shutdown="SHUTDOWN">
    <Service name="Catalina">
        <!--Before editing -->
        ....
        <!-- Define an AJP 1.3 Connector on port 8009 -->
        <!--
        <Connector protocol="AJP/1.3"
                address="::1"
                port="8009"
                redirectPort="8443"
                maxParameterCount="1000"
                />
        -->

        <!-- After editing -->
        ....
        <!-- Define an AJP 1.3 Connector on port 8009 -->
        <Connector protocol="AJP/1.3"
                address="127.0.0.1"
                port="8009"
                tomcatAuthentication="false"
                packetSize="32768"
                redirectPort="8443"
                allowedRequestAttributesPattern=".*"
                secret=""/>
    </Service>
</Server>

The .port and .secret need to be the same values as used when configuring the ISAPI redirector plugin. If the Easit GO service is started these changes will NOT take effect until the service is restarted.

AJP Connector Configuration Reference

Configure Application Pool and Site in IIS

If IIS (Microsoft Internet Information Services) is not installed or enabled on your server, we refer you to the official docs from Microsoft.

Each instance of Easit GO on the server have a application pool and site configured in IIS.

IIS-Overview

In this guide we will use Windows PowerShell to add and configure a Application Pool and Site in IIS and we start by setting some variables and creating an Application Pool.

1
2
3
4
$SiteName = 'EasitGO-Prod'
$WwwRoot = 'D:\Easit\wwwroot\EasitGOProd'
$IsapiRoot = 'D:\Easit\ISAPI\EasitGOProd'
New-WebAppPool -Name "$SiteName"

Then we create a site connected to the application pool and create a virtual directory.

1
2
New-WebSite -Name "$SiteName" -Port 80 -ApplicationPool "$SiteName" -PhysicalPath "$WwwRoot"
New-WebVirtualDirectory -Site "$SiteName" -Name jakarta -PhysicalPath "$IsapiRoot\bin"

Last but not least we add the ISAPI filter.

1
2
Add-WebConfigurationProperty -pspath 'MACHINE/WEBROOT/APPHOST' -filter "system.webServer/security/isapiCgiRestriction" -name "." -value @{path="$isapiRoot\bin\isapi_redirect.dll";allowed='True';description="$SiteName"}
Set-WebConfiguration //System.webServer/isapiFilters -metadata overrideMode -value Allow -PSPath IIS:/

Please visit the docs for Tomcat Connector - ISAPI redirector for Micrsoft IIS HowTo for further reading, configurations and more details.

Enable SSO against a Active Directory (SSO with IWA)

"SSO" via Active Directory is achieved by activating Windows Authentication for the site handling incoming requests for Easit GO in IIS.

Please use Microsofts official docs for, Windows Authentication, to activate Windows Authentication.