3. How do I set up a Webauth protected service?

There are three basic options available to create a Webauth protected service.

  • If you are running Apache 2 (on either Unix or Windows based systems) you should build and install mod_webauth for your Apache server. See section 3.1.
  • If you are running IIS you should seriously consider the Webauth for IIS implementation.
  • If you have a Java based system, the SPIE project has produced a Java implementation of Webauth. This option almost certainly requires a reasonable amount of Java expertise to get working.

3.1.

To set things up with Apache 2 you need to have a working Apache 2 server (with SSL support). Download and compile the Webauth v3 source. The Webauth v3 source has some prerequisites:

  • OpenSSL
  • MIT Kerberos v5
  • cURL

See the Obtaining and Installing notes from the Stanford Webauth pages for the precise details of versions required.

Once the Webauth module is built and installed you need to:

  • Make sure your system clock is correct and that you are running some form of regular system time synchronisation.
  • install a configuration file for the kerberos libraries
  • create a kerberos keytab for your Webauth protected service (please email sysdev@oucs.ox.ac.uk for help with this, we need to know the name of the machine that will be running the service. If you are not ITSS responsible for the unit in question please direct your request through them; currently the management of service keytabs is the responsibility of the unit ITSS.)
  • configure apache to make use of the webauth module
  • Double check that your system clock is correct and that you are running some form of regular system time synchronisation.

A minimal kerberos configuration would be (in /etc/krb5.conf):

[libdefaults]
        default_realm = OX.AC.UK
        dns_lookup_kdc = true

[realms]
OX.AC.UK = {
        admin_server = kdc-admin.ox.ac.uk
}

[domain_realm]
        .ox.ac.uk = OX.AC.UK
        ox.ac.uk = OX.AC.UK
    

The above config assumes your Kerberos client implementation supports finding the KDCs by DNS lookup of SRV records (most do).

There are currently four KDCs in service: kdc0.ox.ac.uk, kdc1.ox.ac.uk, kdc2.ox.ac.uk and kdc3.ox.ac.uk. If you are encountering problems and seek a definitive answer as to which KDCs serve the OX.AC.UK realm at any point in time then a DNS lookup for the SRV records at _kerberos._udp.ox.ac.uk will provide the answer. On a UNIX system, say on linux.ox.ac.uk, one way to do this lookup is with the command dig -t SRV _kerberos._udp.ox.ac.uk

If your implementation does not support configuration by DNS then the realms section should contain the above hostnames in a random order, for example:

[realms]
OX.AC.UK = {
        kdc = kdc1.ox.ac.uk
        kdc = kdc3.ox.ac.uk
        kdc = kdc0.ox.ac.uk
        kdc = kdc2.ox.ac.uk
        admin_server = kdc-admin.ox.ac.uk
}
    

Apache configuration is in two parts, some general configuration directives, and some per location directives. File locations can be absolute or as below relative to the apache installation root.

# Make webauth available
LoadModule webauth_module modules/mod_webauth.so

# Set locations for various files used by mod_webauth
WebAuthKeyring webauth/keyring
WebAuthKeytab  webauth/keytab
WebAuthServiceTokenCache webauth/service_token_cache
WebAuthCredCacheDir webauth/cred_cache

# Point to the Oxford Webauth service
WebAuthLoginURL https://webauth.ox.ac.uk/login
WebAuthWebKdcURL https://webauth.ox.ac.uk/webkdc-service/
WebAuthWebKdcPrincipal service/webkdc@OX.AC.UK

# If you're having trouble switch on debugging
#WebAuthDebug on
    

For each location that you want to protect using Webauth you should add a section like:

<Location /private>
  WebAuthExtraRedirect on
  AuthType WebAuth
  require valid-user
</Location>
    

Note that the above example would allow into /private all users who have a University of Oxford Single Sign-On username and password, including Virtual Card holders who are not members of the University. You may need to check the username against a list of those you wish to allow into /private.

Up: Contents Previous: 2. How does it work? Next: 4. How do I log out of Webauth, or a Webauth enabled application?