1. What is WebAuth for IIS?
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
2. What are the system pre-requisites?
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
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
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).
3. What are the software dependencies?
WebAuth for IIS has two software dependencies.
3.1. Visual C++ 2008 Redistributable Package
The Visual C++ Redistributables are included in the installer
(and can also be downloaded from Microsoft's downloads site).
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.
3.2. MIT Kerberos for Windows
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
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.
4. How do I install WebAuth for IIS?
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.
5. How do I configure IIS after 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
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
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.
6. How do I know if it's working?
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.
7. What next?
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.