Help is always at hand

Home » Support » Documentation » Installation » Integration with a Web Server

Integration with a Web Server

1. Apache

  1. 1.1) Make sure that you have configured Apache to use the Prefork MPM (not the Worker MPM) to avoid hangs caused by an AJP bug. See here for details.
  2. 1.2) Ensure that an AJP connector is defined in your [tomcat]/conf/server.xml file. This is the case by default, so you probably don't need to change anything. There should be a line like the following in server.xml: <Connector port="8009" protocol="AJP/1.3" redirectPort="8443" /> If you need to edit server.xml then restart Tomcat afterwards.
  3. 1.3) Enable mod_proxy and mod_proxy_ajp in Apache. For example, uncomment the 2 'LoadModule' lines that will look something like this:
    LoadModule proxy_module /usr/lib/apache2/mod_proxy.so
    LoadModule proxy_ajp_module modules/mod_proxy_ajp.so
  4. 1.4) Add the following statement to the configuration file for your virtual host (or, if you are not using virtual hosts, your httpd.conf file):
    ProxyPass /asset-bank ajp://<tomcat server>:8009/asset-bank retry=0 If you are running Tomcat on the same machine as Apache you should use ‘localhost’ as the tomcat server name: ProxyPass /asset-bank ajp://localhost:8009/asset-bank retry=0
  5. 1.5) Restart apache
  6. 1.6) The application should now be availble to view at http://<server name>/asset-bank/
  7. 1.7) For more information on using mod_proxy_ajp to combine Apache and Tomcat read the mod_proxy_ajp documentation

2. IIS

In these instructions, we have assumed that Tomcat is installed in a directory called c:\jakarta-tomcat. Adapt the instructions according to where you have it installed. It is also assumed that the webapp will be called 'asset-bank'.

Note: If you are running IIS on a separate server to Tomcat, please read this knowledgebase article.

2.1 Setting up the ISAPI Filter

For IIS 6

  1. 2.1.1) Download isapi_redirect.dll (or isapi_redirect.dll for 64 bit machines), workers.properties, uriworkermap.properties, rewrites.properties and isapi.log.
  2. 2.1.2) Place isapi_redirect.dll in c:\jakarta-tomcat\bin\win32 (create the sub-directory if necessary). You need to ensure that the following IIS and service accounts have permission to read and execute this file:
    • Network Service
    • IIS_WPG
    • Internet Guest Account(<machine_name>\IUSR<machine_name>)
  3. 2.1.3) Place the properties files in your Tomcat conf directory, i.e. c:\jakarta-tomcat\conf. Add permissions as above for the IIS accounts.
  4. 2.1.4) Open the file workers.properties and check that the values for workers.tomcat_home and workers.java_home are correctly mapped to your tomcat and java installation locations respectively.
  5. 2.1.5) Place the file isapi.log in your tomcat logs directory, i.e. c:\jakarta-tomcat\logs. Make sure that the IIS user account(s) have permission to read from, execute and also write to this file.
  6. 2.1.6) Download the file isapi_filter.reg and open it in a basic text editor.
  7. 2.1.7) In the file replace all instances of 'c:\\jakarta-tomcat' with the actual path to your tomcat installation (remember to replace all \'s with \\ in the path).
  8. 2.1.8) Double click on the file isapi_filter.reg to update your registry with the necessary keys.
  9. 2.1.9) Using the IIS management console, add a new virtual directory to the Default 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 c:\jakarta-tomcat\bin\win32). While creating this new virtual directory assign it the execute access.
  10. 2.1.10) Using the IIS management console, add isapi_redirect.dll as a filter in your web site. Take Properties for the Default Web Site, and select the ISAPI Filters tab. The name of the filter should be 'jakarta', its executable must be our c:\jakarta-tomcat\bin\win32\isapi_redirect.dll.
  11. 2.1.11) (IIS 6) Using the IIS management console, select Web Service Extensions in the IIS Console Server Tree. Add a new extension called Jakarta Tomcat (this can be anything), add isapi_redirect.dll as the associated file (browse to the file, e.g. c:\jakarta-tomcat\bin\win32\isapi_redirect.dll) and select Set extension status to Allowed.
  12. 2.1.12) Restart tomcat
  13. 2.1.13) Restart IIS (restart the IIS service, e.g. in the manager console choose the Server, right-click, choose All Tasks, choose Restart IIS).
  14. 2.1.14) The application should now be availble to view at http://<server name>/asset-bank/

For IIS 7

As above, but replace steps 2.1.9 - 2.1.11 with the following to configure IIS 7:

  1. Open IIS 7 Manager
  2. Navigate to your host.
  3. Double click on the ISAPI and CGI Restrictions icon. On the right hand panel, click ‘Add...’. Point the path to your isapi_redirect.dll file and give it a description ‘tomcat’. Check "Allow extension path to execute"
  4. Now, click on the Default Website and navigate to ISAPI Filters. On the right hand panel, click on Add... and point to your isapi_redirect.dll file, give the filter a name (‘tomcat’).
  5. Navigate to your Default Website again. Add a virtual directory and name it ‘jakarta’, point this to the directory containing isapi_redirect.dll
  6. Click on the newly created virtual directory jakarta. Navigate into Handler Mappings, on the right hand side you will see a panel called Actions. Click on Edit Feature Permissions and tick the execute permission.
  7. To allow the upload of files larger than 30 mb, please read: Why can't I upload large images over IIS?
  8. Finally, navigate to your host context again and do a restart.

IIS Integration Troubleshooting

When I attempt to browse to http://<server name>/asset-bank I get a blank page/page not found error:
This normally means that the ISAPI redirect filter hasn't loaded correctly (you can check this by looking at the 'Isapi Filters' tab of the properties for the IIS site, if the filter is shown with a red downward pointing arrow it means it hasn't loaded). If the filter hasn't loaded correctly then there are a few potential problems to check:

  1. Are the permissions correct? The ISAPI filter will only load if the IIS user accounts have read and execute access to all three properties files and isapi_redirect.dll, and read, write and execute access to isapi.log. If you are experiencing errors due to permissions, then you could initially allow 'Everyone' read, write and execute permissions on all files, in order to establish that the ISAPI plugin is working, then tighten the permissions to allow on the required IIS accounts.
  2. Are you installing onto 64bit Windows? If so, have you used the 64bit version of isapi_redirect.dll? If both of these are true and the filter still isn't loading it might be the case that your installation of IIS is using a 32bit version of ASP.NET. The following article explains how to change IIS to use a 64bit version of ASP.NET:
    http://support.microsoft.com/kb/894435

When I attempt to browse to http://<server name>/asset-bank I get a 'You are not authorized to view this page' error message:
This normally indicates that the permissions on your Asset Bank webapp directory are preventing the IIS guest user from browsing the site. This should be resolved by giving the IIS anonymous access user read and execute permissions on your Asset Bank webapp.

2.2. IIS Forwarding

If you have successfully integrated Tomcat with IIS and would like Asset Bank to be available at http://<server name> rather than just http://<server name>/asset-bank/ then complete the following steps:

  1. 2.2.1) Download default.zip, unzip it and put the file default.asp into the root of your Default IIS website.
  2. 2.2.2) Using the IIS management console make sure that your website has execute permissions for scripts. Select properties for the Default Web Site and select the Home Directory tab. Execute permissions should be set to Scripts only or Scripts and executables.
  3. 2.2.3) Using the IIS management console make sure that your website has Default.asp as a default document. Select properties for the Default Web Site and select the Documents tab. Make sure Enable Default Document is checked and that Default.asp is at the top of the list of default documents.
  4. 2.2.4) (IIS 6) Using the IIS management console, select Web Service Extensions in the IIS Console Server Tree. Make sure that Active Server Pages is Allowed rather than Prohibited.
  5. 2.2.5) Restart IIS (restart the IIS service, e.g. in the manager console choose the Server, right-click, choose All Tasks, choose Restart IIS).
  6. 2.2.6) The application should now be available to view at http://<server name>

2.3. IIS Single-signon

Note that because of changes to enable the Flash Uploader to be used with IIS SSO these instructions require Asset Bank version 3.1127 or above. If you have an earlier version of Asset Bank, and want to enable IIS SSO without upgrading, please contact us.

Note that SSO will not work if unauthenticated users are allowed access, i.e. if the 'Public' group has any permissions (see http://www.assetbank.co.uk/go/knowledgebase/sso_needs_no_public_access.html)

For single sign on to work, you must first have user accounts set up in Asset Bank corresponding to the Windows usernames for the users you would like to have access. This is normally done by synchronising Asset Bank accounts with Active Directory, read instructions for LDAP integration.

  1. 2.3.1. In the IIS management console, select properties on the Default Web Site. On the Directory Security tab, click Edit by ‘Authentication and access control’.
  2. 2.3.2. Check ‘Enable anonymous access’. In the ‘Authenticated access’ section, check the ‘Integrated Windows authentication’ box. Click OK on the dialogs to apply.
  3. 2.3.3. The isapi_redirect.dll should have read permissions for the Internet Guest Account (ie the account that ‘anonymous access’ is set for), and also read permissions for Authenticated Users (i.e. the users who will be logging in via the single sign on).
  4. 2.3.4. Restart IIS.
  5. 2.3.5 Tomcat configuration. Find the Connector element for the AJP connector in [tomcat]/conf/server.xml, and add tomcatAuthentication="false": <!-- Define an AJP 1.3 Connector on port 8009 -->
    <Connector port="8009" protocol="AJP/1.3" redirectPort="8443" tomcatAuthentication="false" />
  6. 2.3.6 In the file ApplicationSettings.properties, set the values of settings as follows:
    sso-enabled=true
    sso-plugin-class=WIASSOPlugin
    show-forgotten-password=false
  7. 2.3.7 Restart the Tomcat service.

If you want non-Active Directory users to log into your Asset Bank then see IIS single sign on (SSO) - supporting non-LDAP users

Single-signon Troubleshooting

If after setting up single-signon you are having problems with form submissions and certain pages not loading this may be to do with the http headers being too large for the integrated authentication setup (this can be confirmed by checking for errors relating to header size in the isapi.log that was setup in 2.1.4). If you think you are experiencing this problem then please try the following resolution:

  1. Ensure that the authentication on the Asset Bank website in IIS is set to anonymous access.
  2. Add a new virtual directory to the Asset Bank website called 'redirector'. This should be mapped to [asset bank iis site root]/redirector on the hard disk (you’ll need to create the ‘redirector’ subdirectory)
  3. Copy the file default.asp from the folder [tomcat home]/webapps/asset-bank/WEB-INF/manager-config/iis to the new 'redirector' IIS websites virtual directory
  4. Make sure that the default.asp is executable
  5. Update the 'redirector' virtual directory in IIS to make use of ‘windows integrated authentication’
  6. Update the default document for the Asset Bank IIS website to use the default.asp in the new virtual directory
  7. Restart tomcat and IIS

Contact Support

Before contacting us, please read contacting our support team.

Email us:
support@assetbank.co.uk

Or, call us on:
+44 (0)1273 923 152