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.
There are 5 basic pre-requisites:
- 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).
WebAuth for IIS has two software dependencies.
- 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)
Download the installer, unzip it into a temporary location and run the installer by double-clicking the setup.exe program. You should see the following dialog box:
Click Install. Once the Visual C++ Redistributables package is installed the WebAuth-IIS installer will continue.
If 'Kerberos for Windows' (KfW) has not been installed the following dialog box will be shown next:
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:
Click Next and the following license agreement dialog box will be shown:
Select I accept the terms in the License Agreement, and click Next, which will cause the next dialog box to be shown:
Select Typical when prompted. The following dialog box will then be displayed, indicating that the installer is ready to install:
Click Install and the installer will perform the installation. When installation is complete the installer will show the Completion dialog box:
Click Finish to return to the desktop.
Double-click setup.exe, and the installer will show the following dialog:
Click Next and the following dialog box will be shown:
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:
After reading select I Agree, and Click Next. An informational dialog box will then be shown:
Read the information, click Next, and you will be shown a dialog box informing you that the installer is ready, and asking you to confirm your intention to install the WebAuth-IIS software:
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:
Navigate to the location of your keytab file, select it, and click Open. You will then be shown the final 'Installation Complete' dialog box:
You should now be ready to configure IIS and test your installation.
Open IIS Manager, find your website in the 'Web Sites' folder in the left-hand pane, right-click on it and select 'Properties'. You should see a dialog box resembling the following:
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\”).
When both fields are set correctly click OK. You should then see the filter has been added but is not active:
Now click OK and reboot your Windows Server machine.
You can use the provided test page to confirm whether it is working correctly.
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.
Copy the provided test file test.asp into the IIS web application directory that you plan to Webauth-protect.
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).
If the WebAuth software is inactive you should see a page resembling the following, with the message “WebAuth is inactive for this location”:
If the WebAuth software is active you should see the familiar University of Oxford Webauth pages. Enter your SSO credentials, and click Login.
Click Continue... below the green tick and you should be redirected to the original test page, which should appear as follows:
If you see the page with a table that includes the above variables (but with values specific to you and your session) you have been successfully authenticated and WebAuth-IIS is working correctly.
Congratulations, your IIS server is now protected by the Webauth service as configured.
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.