Microsoft IIS version 7 Integration
Contents
Overview
This document outlines the steps required to integrate the Internet Information Server (IIS) with Swivel using dual or single channel authentication. The Swivel install requires configuring an agent on the Swivel server and setting up a shared secret with the IIS server to allow communication for authentication. An ISAPI filter installed on the IIS server allows access to protected resources through the Swivel authentication.
NOTE: This document refers to the version of the filter numbered 1.2, and the configuration application with the same version number. 32-bit and 64-bit versions of the filter are available. Version 1.3.4, with PINpad support, is available for 64-bit only.
If Windows 2008 Server server is being used, or only ASP.Net applications are being protected an alternative authentication is available, see Microsoft IIS version 7 ASP.NET Integration
Prerequisites
Internet Information Server on Windows server 2008, 32-bit or 64-bit operating system.
Swivel server
The appropriate Swivel ISAPI filter software can be downloaded from here, depending on your operating system:
The latest release is version 1.3.9. Support for PINpad is included from 1.3.0 onwards. Version 1.3.4 adds PINpad support for change PIN as well:
These links refer to version 1.2 of the filter, provided for legacy purposes.
IIS Filter Version History
1.2 32 bit and 64 bit
1.3.3 (64-bit only): PINpad support added
1.3.4 (64-bit only): added PINpad support for ChangePIN
1.3.5 (64-bit only): enhancements to ChangePIN support
1.3.6 (64-bit only): added a default logout page
1.3.7-9: various bug fixes
Swivel Configuration
On the Swivel server configure the agent that is permitted to request authentication. On the Swivel Administration Console select from the server menu Agents and enter the details of the IIS server IP address and a shared key, then click on apply.
Example:
Name : IIS server 1, Hostname/IP : 192.168.1.1, shared secret : secret
If Single Channel communication is to be used, select from the Swivel Administration Console Single Channel, and set the Allow image request by username to Yes then click on apply.
Configuring the IIS Server
Install the Swivel Filter
1. On the IIS server run the PINsafeIISFilter.exe. The IIS filter may need to be run as an Administrator user (The filter needs to be installed by IIS running as Administrator user but it can run as a normal user).
2. Choose the Path to Install to such as C:\Program Files\PINsafe IIS Filter
3. Select Start Menu Folder
4. When details are correct click on Install
5. If the error ‘Incorrect Command Line Parameters’ is seen click on OK
Create a PINsafe virtual directory
1. On the Internet Information Services Manager right click on the website and select Add Virtual Directory
2. Create an Alias called PINsafe
3. Point the path to the PINsafe directory Web folder, by default C:\Program Files\PINsafe IIS Filter\Web. Test Connection verifies the path, and Connect As allows Application User for pass through authentication.
4. Set the permissions to Read and Run Scripts
Installing the ISAPI Filters, extensions and ASP on IIS
This requires the ISAPI filters, ISAPI extensions and ASP to be installed. To verify or install these, for Windows 2008, on the IIS server start the Server Manager by selecting Start/Administrative Tools/Server Manager then expand the tab for Roles, click on the Web Server (IIS), then look under Role Services to ensure that the ISAPI Filters, ISAPI Extensions and ASP are installed. If it is not click on Add Role Services and add them.
Install the Swivel ISAPI Filter
1. On the Internet Information Services Manager Select the website
2. Select ISAPI filters by double clicking on the ISAPI filters icon
3. Under Actions select Add
4. Select the Path to the Swivel ISAPI filter. Note that the actual file you require will be PINsafeIISFilter.dll, located in the sub-folder Web\bin of the installation folder. Enter a name for the Filter such as PINsafe ISAPI Filter. When information is complete click on Ok.
5. Ensure the Swivel ISAPI filter is the top filter by selecting the 'View Ordered List...'
Configure the ISAPI filter
1. Select Start Programs/PINsafe IIS Filter/Filter Configuration. This will look for the location of config.xml, this will be created when first used and this must be located in web/bin.
Note: If the Swivel Filter Configuration does not exist in the Start Menu, it can be started by running it from its install location. The default install location is C:\Program Files\PINsafe IIS Filter\Web\bin\ConfigApp.exe
2. You will be asked to select the location of the configuration file. It is important that you select the right location. It should be in the same folder as the ISAPI filter. Initially, this file will not exist, but will be created as a result of running this configuration application.
PINsafeIISFilter Options
PINsafeServer: The PINsafe Server tab contains settings which define the Swivel server which will be used to authenticate users.
Hostname/IP: The name or IP address of the Swivel server.
Port: The port number used by the Swivel server (normally 8080, or 8443 for HTTPS).
Context: The context (i.e. web application name) of the Swivel instance on that server
Secret: The common secret used to communicate with the Swivel server. This value must be the same as the secret defined for the Swivel agent configured earlier.
SSL enabled: Tick this box to require SSL (HTTPS) communication with the Swivel server.
Permit self-signed certificates: Tick this box to allow SSL certificates to be self-signed. This also ignores other certificate errors, such as site names not matching.
Authentication: The Authentication tab contains the following settings:
Idle time (s): The time (in seconds) for which the authentication cookie will be valid if the web page is not used.
Username header: The name of a cookie which will pass the username of the authenticated Swivel user. If this value is blank, no cookie will be provided.
Single: Indicates that single channel security strings (i.e. TURing image) are permitted.
Dual: Indicates that dual channel security strings (i.e. via e-mail, SMS) are permitted.
On-demand dual: Indicates that the login page should display a button to request dual-channel security strings.
Display password fields: Indicates that the login page should show a field for Swivel password as well as OTC.
Permit self-reset: Indicates that the user self-reset page should be enabled.
Exclusions and Inclusions: Use the inclusion and exclusion tabs to enter which paths should be protected by Swivel:
Included paths: This is a list of paths within the current website which require Swivel authentication. If this list is empty, the entire website will be protected except as indicated by the Exclusions tab. Paths should be one per line.
Excluded paths: This is a list of paths within the current website which should be exempt from Swivel authentication. This is only relevant if the included paths list is empty, in which case all paths not on this list will be protected by Swivel.
Excluded addresses: This is a list of IP addresses which are exempt from Swivel authentication. All requests from these addresses are passed through without authentication.
Misc: On the Misc tab, edit any custom paths as follows:
Default path: This is the path to which authenticated requests are directed if the login page is targeted directly. If a user tries to access a protected page, she is redirected to the login page, and after authentication, back to the page she was trying to access. If the user requests the login page directly, she will be redirected to this location after authentication.
Logout path: Requesting this path will result in the user being logged out. Subsequent requests will require re-authentication, if relevant. If this path is empty, users can only be logged out by closing the browser, or if the authentication times out. Note: The logout path must be an included file location.
Virtual web path: This is the path to the Swivel authentication pages. See the next section for details on setting this up. You should normally set this to be “/pinsafe”, unless you have a particular reason not to.
Help URL: The URL for Swivel IIS filter help. The filter does not come with help pages as standard, so this should only be filled in if help pages have been provided by the reseller or end user.
After configuration is complete Apply the settings and restart the World Wide Web Publishing Services.
Allow Active Server Pages: to verify this, select the Internet Information Services Manager expand the required server then click on Web Service Extension.
Installing the Filter on Multiple Websites
Most of the instructions above assume that you are installing the IIS filter on the single default website of a web server. However, if you want to use the filter on multiple websites on the same server, you need to carry out a few extra steps.
Firstly, if all the settings on all the websites are exactly the same, you can configure it once, and then carry out the same steps to activate the filter on each website.
If, however, you need different settings for each website, you will need to do the following for all except the first website:
1. Make a copy of the entire Web folder, including the bin sub-folder. You can copy it as a sub-folder of Swivel IIS filter, with a different name, or you can put it somewhere completely different. It is important, however, that you keep the structure the same – all the .asp files must remain intact, and the filter DLL must be in a sub-folder called “bin”.
2. When you come to configure each filter, navigate to the bin sub-folder of the copy you have just made. Otherwise, configuration is exactly as before.
3. When selecting the IIS filter to install, and also when defining the virtual directory for Swivel web pages, you should use the copy you have just created, rather than the original. This is important, as both the filter and the web pages look for the configuration file relative to their own location.
Testing
Browse to a web page that has been configured for protection. This should display a Swivel login dialogue:
Enter the Username.
For dual channel, enter the One Time Code:
Or click start session to enter a single channel OTC. The Swivel log will record that a single channel session has started.
If authentication is successful it should redirect to the login page. If failed an error message will appear. The Swivel log will record any successful log attempt for the agent.
Uninstalling the filter
To remove the Filter, remove role services that are not required by other applications, to do this for Windows 2008, on the IIS server start the Server Manager by selecting Start/Administrative Tools/Server Manager then expand the tab for Roles, click on the Web Server (IIS), then look under Role Services to remove the ISAPI Filters, ISAPI Extensions and ASP are installed. The system will require a restart to complete.
From the IIS Manager right click on the Swivel Virtual Directory, then select Remove, Click on Yes to Confirm.
To uninstall the Swivel IIS Filter, choose Start/All Programs/PINsafe IIS Filter/PINsafe IIS Filter Uninstaller, then click Yes on the confirmation to uninstall.
The Swivel Filter config may be left after uninstalling, so to completely remove this, remove the folder Program Files\PINsafe IIS Filter.
Troubleshooting
Verify the correct filter version has been installed for the operating system i.e. 32 bit or 64 bit.
Check for error messages in the Swivel log
Check the IIS log messages
Filter Install issues: The IIS service needs to run as an administrator in order to install the filter. Once the filter is installed, it will run as the normal user. Open the Services applet and locate World Wide Web Publishing. Select properties, then go to the Log On tab. Assuming you are logged in as an administrator, select Local System account. Then restart the service. Hopefully, this will start the filter. You can then switch back to the default account and restart again.
If you are not redirected to the Swivel login page when trying to access a protected page, open IIS manager and check that the ISAPI filter is installed and has loaded properly (there should be a green arrow next to it, and the priority should be “High”). If this is not the case, restart IIS, if you have not already done so, and try again. The filter doesn't try to install until you try to access a web page from that website, so try that before assuming it hasn't worked.
If the filter is listed, but showing a red cross, then it failed to start. In this case, check the error messages in the event log showing.
If the filter shows as green, with priority unknown, it may not be installed. In this case, you need to check. You can do this with a debug viewer, such as the one supplied by SysInternals (http://technet.microsoft.com/en-us/sysinternals/bb896647.aspx). Download this and run it (there's no need to install it) on the server, then restart IIS. If you don't see any messages relating to the Swivel IIS filter, then it's not installed properly.
If the page is still not redirected, try the following:
1. Check which application pool your web application is running as, then go to the properties page for that application pool.
2. On the Identity tab, change the user to “Local System”. You will be warned that this is a potential security risk, but don’t worry – it won’t be left like this.
3. Restart IIS.
4. Try accessing a protected page again. Hopefully this time you will be redirected.
5. You can now go back to the application pool and change the identity back to what it was originally: it would appear that it is only necessary to run as an administrator to get the filter to register initially.
If you do not see a Turing image when using start session then in a web browser test the following link from the IIS server. If an image is not seen, then there is a problem either with communicating with the Swivel server or the Allow Image request by username may be set to No.
For a virtual or hardware appliance Install
https://<pinsafe_server_ip>:8443/proxy/SCImage?username=<username>
For a software only install see Software Only Installation
If the web page is redirected to the /PINsafe/login.asp page but an error message appears then ensure that the Active Server Pages are allowed. To verify this select the Internet Information Services Manager expand the required server then click on Web Service Extension.
No authentication on main page
Open IIS Manager and disable Anonymous authentication for the root folder. Refresh the browser to prevent caching and try again.
You may need to ensure that Anonymous authentication is enabled for the PINsafe folder, though, so you don't run into problems showing the TURing image.
Authentication working internally but not externally
If it is working internally, but not externally, ensure that there is no caching by openine a new browser. Also specify the default redirect URL as "/default.htm", rather than "./default.htm". The latter will redirect to default.htm within the pinsafe folder.
Error Messages
AgentXML request failed, error: The agent is not authorised to access the server
User fails to authenticate with the above error message in the Swivel log. An Agent on Swivel server has not been defined for the IIS server. Go to Server/Agents in the Swivel admin console, and add a new entry, using the IP address of the IIS server. Make sure the agent secret is the same as on the IIS filter configuration.
This installation package is not supported on this processor type. Contact your product vendor
