The WebAuth for IIS software is a development of software originally produced as a deliverable from a research project at Leland Stanford Junior University. The main binary is an ISAPI filter, intended for IIS 6.x on Windows Server 2003.
Installing the required software manually proved to be potentially error-prone so Sysdev at OUCS have developed an installer to make the installation and configuration process easier. Some familiarity with Windows Server administration is assumed.
- You should be running Windows Server 2003 x86, with the Application Server role activated. All applicable security patches should be applied. Later Windows Server OS releases are not supported, as the WebAuth for IIS ISAPI filter is unsuitable for use with 64-bit Windows Server releases.
- The WebAuth protocol should communicate securely, so IIS should be set up with a valid SSL certificate. Instructions for obtaining and setting up IIS 6.x with an SSL certificate are documented here.
- Email email@example.com, requesting a service principal for webauth/yourserver.subdomain.ox.ac.uk@OX.AC.UK (substituting your server details instead of yourserver.subdomain) requesting that your username/itss principal (where username is your SSO username) should be granted admin rights over the service principal. See Section 3.1 of this WebAuth wiki page entitled 'Obtaining your Webauth keytab' for more information about this process. See section 2.1. for more information about creating and installing the service principal locally.
- Ensure that your system clock is correct and that you are running some form of regular system time synchronisation. This is important for WebAuth and Kerberos. Configuring your Windows Server as an NTP client is beyond the scope of this document (See Microsoft's guide to the Windows Time Service for more information).
- Decide which web application directory you want to protect with the Webauth service if not the web root (the installer will request this directory location at installation time).
Once the service principal has been created by sysdev you can create the server keytab using the kadmin utility on a workstation that has been secured for this purpose. (since linux.ox.ac.uk is a shared service it is not recommended for this). An example of creating a keytab for a Webauth service principal webauth/hygmod.oucs.ox.ac.uk@OX.AC.UK on a linux workstation follows:
Once the keytab has been created you can securely transfer it to your WS2003 server. The putty download page offers psftp, a command-line SFTP client that will allow you to pull the client from the secure workstation to your Windows server over a secure connection. Alternatively if you prefer an SFTP GUI, WinSCP offers similar functionality and is available from the WinSCP download page.
It is important that you restrict access to the keytab file once it is transferred. Permissions to access the keytab file should only be granted to the accounts SYSTEM (full permission), the Administrators group (full permission), and IIS_WPG (read permission only).
- Microsoft Visual C++ 2008 Redistributable Package (x86) (See section 3.1. Visual C++ 2008 Redistributable Package)
- MIT Kerberos for Windows (See section 3.2. MIT Kerberos for Windows)
Click Yes and the installer will close. In its place a browser window will open showing the KfW download page. Browse to the latest version (v3.2.2 at the time of writing), download the KfW 'msi' installer file and run it. You should see the following dialog box:
Most users will want to keep Overwrite krb5.ini ticked to accept the default OX.AC.UK Kerberos configuration. If you have a pre-existing Kerberos configuration that you want to keep you should untick Overwrite krb5.ini. Click Next. The following dialog box will then be shown, this time asking for the installation location:
Click Next to accept the default location (unless you have reasons to change the default value to a custom location) and a dialog box will be shown asking you to agree to the terms of the software license:
Click Next and the installer will perform some installation tasks, only pausing to request configuration information that it cannot find for itself. A 'Browse for Directory' dialog box will be shown requesting the location of the protected web application directory:
Navigate to the IIS web application directory that you intend to Webauth-protect, and click OK when you have done so. The installer will then request the location of your Kerberos keytab file with a 'Browse for File' dialog box:
Select the ISAPI Filters tab, click Add..., enter a text name in the Filter name field (e.g. “SUWA”) and then click Browse... to find and select the 'SUWA_IIS6.dll' executable file that was installed in the installation folder that you specified during WebAuth-IIS installation (If you did not change the default location it should be in “C:\Program Files\Stanford\WebAuth-IIS\”).
Ensure that the Web Service Extension Active Server Pages is activated in the IIS Manager application (this can be found by opening the Internet Information Services (IIS) Manager application in the Administrative Tools section of the 'Start' menu and navigating to the Web Service Extension folder under your 'local computer' in the left-hand pane of the IIS Manager window.
Start a browser and connect over HTTPS to the test.asp file that you placed in your IIS instance, using the same hostname in the URL as is on your certificate, to test that your IIS instance is running (from the same machine it may be something like “http://yourserver.subdomain.ox.ac.uk/test.asp” if you have decided to protect the entire Web Application).
You can now remove any test pages, disable the Web Service Extension 'Active Server Pages' in the IIS Manager application if it was activated for testing in 6. How do I know if it's working? (and is no longer required), and deploy your web applications.