These instructions cover setting up integration with IIS 7.0, 7.5 or 8.0.
You can run IIS and Asset Bank on the same machine or different machines. These instructions cover both scenarios.
In these instructions, we have assumed that Tomcat is installed in a directory called C:\Tomcat. Adapt the instructions according to where you have it installed. It is also assumed that the Asset Bank webapp is called 'asset-bank'.
For more information see http://tomcat.apache.org/connectors-doc/webserver_howto/iis.html and linked articles.
1. Setting up the ISAPI Filter
This will allow web browser clients to access Asset Bank by connecting to IIS instead of directly to Tomcat. The isapi_redirect.dll ISAPI filter will run inside IIS and proxy requests to Tomcat. This configuration allows you to place Tomcat behind a firewall (IIS needs access to Tomcat but web browser clients do not) and is also a prerequisite for WIA SSO (which is described in section 2.3).
- Download asset-bank-proxy_32bit.zip, or asset-bank-proxy_64bit.zip if your IIS worker processes run in 64 bit mode. If you're not sure use these instructions to find out.
- Extract into C:\inetpub on the IIS machine. This will create a subdirectory C:\inetpub\asset-bank-proxy.
- Ensure that the following IIS and service accounts have permission to read and execute contents in C:\inetpub\asset-bank-proxy\
- Network Service
- If you are running Tomcat on a different machine from IIS then edit workers.properties and set worker.ajp13.host to the name (or IP address) of the machine running Tomcat.
- If you have changed the Tomcat AJP port then edit workers.properties and set worker.ajp13.port to the port that Tomcat is listening on for AJP connections.
- Additional to the default IIS features ensure that the following are also installed
- ASP (used for IIS forwarding)
- ISAPI Extensions
- ISAPI Filters
- Open the "Internet Information Services (IIS) Manager".
- Navigate to your host and 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".
- Click on the Default Website (inside Sites) and then double click on "ISAPI Filters". On the right hand panel, click on Add... and point to your isapi_redirect.dll file, give the filter a name (‘tomcat’).
- Navigate to your Default Website again. Add a virtual directory (using the right click menu) and name it ‘jakarta’, point this to the directory containing isapi_redirect.dll (C:\inetpub\asset-bank-proxy).
- Click on the newly created virtual directory 'jakarta'. Double click on "Handler Mappings", on the right hand side you will see a panel called "Actions". Click on "Edit Feature Permissions..." and tick the execute permission.
- To allow the upload of files larger than 30 mb, please read: Why can't I upload large images over IIS?
- Finally, navigate to your host again and restart IIS.
Running Asset Bank from the ROOT webapp
To change the default webapp name from asset-bank to something else or run it from the ROOT webapp you need to edit uriworkermap.properties. To run it from the ROOT webapp replace the existing two lines with the line below.
You will now also need to move the content of \webapps\asset-bank\ into \webapps\ROOT\. Afterwards you can delete \webapps\asset-bank\.
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. If the filter hasn't loaded correctly then there are a few potential problems to check:
- 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.
- 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:
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.
When I attempt to browse to http://<server name>/asset-bank I get a terse"The service is unavailable." message:
This can indicate that the worker.ajp13.host in workers.properties is incorrect. Check isapi.log - there should be an error message in it.
2. Optional Advanced Configuration
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:
- Go to Windows Features (the same tool used in 1.8 above) and enable Internet Information Services -> World Wide Web Services -> Application Development Features -> ASP.
- Download default.zip, unzip it and put the file default.asp and default.aspx into the root of your Default IIS website.
- Using the IIS Manager make sure that your website has Default.asp as a default document. Click on the Default Web Site and then double click on "Default Document" tab. Make sure that default documents are enabled (see 'Enable' link in the right hand Actions panel) and that Default.asp is at the top of the list of default documents.
- Restart IIS (restart the IIS service, e.g. in the manager console choose the Server, right-click, choose All Tasks, choose Restart IIS).
- The application should now be available to view at http://<server name>.
- If you are not redirected to the Asset Bank homepage but instead see a 'New Application Failed' error it is likely that IIS is having trouble executing the classic ASP page (this can happen with later version of IIS). Repeat steps 2.2.3 to 2.2.5 but make 'default.apsx' the first default document.
2.3. IIS Single sign-on
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.
Please note: Integrated Windows authentication does not work over HTTP proxy connections.
Note that SSO will also not work if unauthenticated users are allowed access, i.e. if the 'Public' group has any permissions (see this article)
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.
- In IIS Manager, go to the Default Web Site and then double click on the "Authentication" icon in the icons pane on the right.
- Ensure that both "Anonymous Authentication" and "Windows Authentication" are enabled. If Windows Authentication is not present here you can install it via Server Manager > Add Roles and Features, then expand the IIS features under 'Security' and check the 'Windows Authentication' box before completing the installation as you would any server role.
- The isapi_redirect.dll should have permissions set so that it can be read and executed by the IUSR (ie the account that is used for anonymous access), and also Authenticated Users (i.e. the users who will be logging in via the single sign on).
- Restart IIS.
- 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" URIEncoding="UTF-8" />
- In the file ApplicationSettings.properties, set the values of settings as follows:
- 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
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 set up above). If you think you are experiencing this problem then please try the following resolution:
- Ensure that the authentication on the Asset Bank website in IIS is set to anonymous access.
- 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)
- 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
- Make sure that the default.asp is executable
- Update the 'redirector' virtual directory in IIS to make use of ‘windows authentication’
- Update the default document for the Asset Bank IIS website to use the default.asp in the new virtual directory
- Restart tomcat and IIS