Legacy Product

Fusion 5.10
    Fusion 5.10

    Set Up Windows Authentication

    Appkit can be used with Integrated Windows Authentication for single sign on (SSO) in your search application using Microsoft Internet Information Services.

    This article includes all the necessary steps to configure the IIS component on the Windows server. These instructions assume that your Appkit application is managed as a Maven project with all project dependencies described in a Maven POM file.

    All screen shots and references to IIS configuration below were obtained from IIS 8.0 on a Windows Server 2012 VM. These might differ if using a different version of Windows or IIS.

    Interaction diagram

    Interaction diagram

    1 Prerequisites

    1.1 Make sure IIS is installed on your Windows server

    Install IIS on your Windows server.

    1.2 Install the Oracle JDK on the Windows server

    Install the Oracle Java SE Development Kit.

    1.3 Install Tomcat

    Tomcat versions 7 and 8 are both supported. In this, we assume you are using Tomcat 8.0.21.

    To install Tomcat

    1. Download the Tomcat installer (Windows Service Installer .exe) and follow the installation instructions. After installation is complete, do not start the Tomcat service just yet.

      Install Tomcat at a whitespace-free path (for example, D:\tomcat8). This path will be referred to as CATALINA_HOME hereafter. All the screenshots that follow assume you installed Tomcat in D:\Tomcat8.

      IIS screenshot

    2. After the installation is complete, change Tomcat memory settings as follows:

      1. Run %CATALINA_HOME%\bin\Tomcat8w.exe

      2. On the Java tab, set Java Options to include:

        -Xms512m
-Xmx2048m
-XX:PermSize=128m
-XX:MaxPermSize=1024m

    3. Repeat these settings in the input boxes below:

      Initial memory pool: 512
Maximum memory pool: 2048

      IIS screenshot

      IIS screenshot

      IIS screenshot

    1.4 Verify the Tomcat installation

    Start up Tomcat via Windows Services and go to http://localhost:8080. You should be presented with the default Tomcat manager application.

    2 Configure and deploy the Appkit application

    2.1 Configure the security provider

    Authentication against IIS requires the "generic" Appkit security provider module. This is a thin layer which integrates with the standard Java servlet API to pick up the user’s credentials for authentication. To enable this module first remove any existing security provider dependency from the pom.xml under the root of the project and add this within the dependencies tag:

    <dependency>
 <groupId>twigkit</groupId>
 <artifactId>twigkit.security.core</artifactId>
 <version>${project.parent.version}</version>
</dependency>

    Then to configure Appkit to invoke this module on startup change the security.conf file in src/main/resources/conf/security/ to contain:

    type: generic

    Make sure to remove any existing security provider configuration if there is one including the 'Spring Security' XML file and Spring related entries in the web.xml file if Spring was previously being used in the application.

    2.2 Deploy the application to Tomcat

    After these steps are completed, package your Appkit web application as a WAR file and deploy into Tomcat. Hereafter we assume you package the application as myapp.war so that the application can be accessed as http://localhost:8080/myapp/.

    3 Configure the Tomcat-ISAPI connector

    The Tomcat ISAPI connector is a DLL file that you can download from the Apache Tomcat website.

    Below, we assume that you have downloaded the ZIP file relevant to your OS type and extracted isapi_redirect.dll from the archive.

    3.1 Configure Tomcat for ISAPI

    1. Add isapi_redirect.dll to %CATALINA_HOME%\bin.

    2. Create %CATALINA_HOME%\conf\workers.properties.minimal with:

      worker.list=worker1
worker.worker1.host=127.0.0.1
worker.worker1.port=8009
worker.worker1.type=ajp13

    3. Create %CATALINA_HOME%\conf\uriworkermap.properties with:

      /*=worker1

    4. (Important) In %CATALINA_HOME%\conf\server.xml, you must put tomcatAuthentication="false" on the AJP connector:

      <Ajp13Connector port="8009" tomcatAuthentication="false" />

      IIS screenshot

    From now on, we assume you installed Tomcat in D:\Tomcat8 as noted above.

    3.2 Configure Windows registry settings

    This key needs to be modified in the registry with the specified properties:

    HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Jakarta Isapi Redirector\1.0

    IIS screenshot

    1. Add a string value with the name extension_uri and a value of /jakarta/isapi_redirect.dll

    2. Add a string value with the name log_file and a value pointing to where you want your log file to be (for example, D:\Tomcat8\logs\isapi.log).

    3. Add a string value with the name log_level and a value for your log level (can be debug, info, error or emerg).

    4. Add a string value with the name worker_file and a value which is the full path to your workers.properties file (for example, D:\Tomcat8\conf\workers.properties.minimal)

    5. Add a string value with the name worker_mount_file and a value which is the full path to your uriworkermap.properties file (for example, D:\Tomcat8\conf\uriworkermap.properties)

      To save trouble, you can create a file named tomcat_iis_settings.reg that includes this (replacing D:\Tomcat8 with your own CATALINA_HOME):

      Windows Registry Editor Version 5.00
[HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Jakarta Isapi Redirector\1.0]
@=""
"extension_uri"="/jakarta/isapi_redirect.dll"
"log_file"="D:\\Tomcat8\\logs\\isapi_redirect.log"
"log_level"="error"
"worker_file"="D:\\Tomcat8\\conf\\workers.properties.minimal"
"worker_mount_file"="D:\\Tomcat8\\conf\\uriworkermap.properties"

    6. On the Windows server, double-click the tomcat_iis_settings.reg file to import the settings.

      IIS screenshot

    4 Configure the IIS

    This assumes that IIS is already installed on the Windows server.

    4.1 Enable ISAPI Filters and ISAPI Extensions

    ISAPI Filters and ISAPI Extensions

    4.2 Enable Windows authentication

    BASIC (optional) and Windows authentication

    4.3 Enable CGI filtering

    CGI filtering on the IIS

    4.4 Configure the virtual directory and website on IIS

    1. Using the IIS management console, add a new virtual directory to your IIS/PWS web site. The name of the virtual directory must be jakarta. Its physical path should be the directory where you placed isapi_redirect.dll (in our example, it is D:\Tomcat8\bin). While creating this new virtual directory assign it with execute access.

      IIS screenshot

      IIS screenshot

      IIS screenshot

    2. Using the IIS management console, add isapi_redirect.dll as a filter in your IIS/PWS web site. The name of the filter should reflect its task (here we use the name jakarta). Its executable must be D:\Tomcat8\bin\isapi_redirect.dll.

      IIS screenshot

      IIS screenshot

      IIS screenshot

      IIS screenshot

      IIS screenshot

    3. Enable Windows authentication for your IIS website:

      IIS screenshot

      IIS screenshot

      IIS screenshot

      IIS screenshot

      IIS screenshot

    4. On IIS Admin, select the server, and click ISAPI and CGI Restrictions. Then open it and Add… with the correct isapi_redirect.dll path:

      IIS screenshot

      IIS screenshot

      IIS screenshot

      IIS screenshot

      IIS screenshot

    5. Restart IIS and Tomcat.

    5 Verify the installation

    If all goes well, you should be able to visit http://localhost/myapp/, which should present the authenticated Windows user to the Appkit application.

    At this point, Tomcat would still be accessible on port 8080, so if you visit http://localhost:8080/myapp/, you should see the same interface, except that your user is not authenticated.

    6 Troubleshooting

    Users receive the error 'the request entity is too large' in the browser

    This is usually due to an issue with the Tomcat-ISAPI communication and the settings of the AJP connector in Tomcat must be modified to increase the maximum packet size:

    1. In the workers.properties file referenced by the tomcat-connection definition, set the packet size to the maximum:

      worker.<worker name>.max_packet_size=65536

    2. Set packetSize in the AJP Connector definition:

      <Connector port="8009" protocol="AJP/1.3" redirectPort="8443" packetSize="65536" tomcatAuthentication="false" />