IT Services



Oxford Webauth HOWTO


Contents



1. What is Webauth?

Webauth is a system developed at Leland Stanford Junior University providing single sign-on for web based services. Single sign-on means that users of Webauth authenticated services, enter a username and a password only once (per session) to a central login server. Any further access to other Webauth based services are automatically and securely authenticated without the user being aware that this has happened.

Webauth is currently implemented as an authentication module for Apache 2. Given an SSL based Apache 2 server it is very easy to configure a Webauth protected service.

Webauth is currently based around (but not limited to) Kerberos 5, a general network single sign-on system developed at MIT. In essence Webauth encapsulates Kerberos tickets into cookies which, when unpacked by the server, provide proof of the identity of the user of the connecting browser.

Webauth protected services never need to see the password of the user because they make use of a trusted third party to verify the identity of the user. The advantage of this is that compromise of a single Webauth protected service does not automatically lead to password compromise for all other Webauth services.



2. How does it work?

This is just a brief summary glossing over many details. For the full story see the Webauth protocol specification.

When a browser connects to a Webauth protected service for the first time, no Webauth service cookie is presented so the server redirects the browser to the Webauth login page. After successful authentication the Webauth login server sets a cookie that will be returned to the Webauth login server and proves to the Webauth login server that the user has successfully authenticated. The Webauth login server then redirects the browser back to the Webauth protected service. The redirect contains information that proves the identity of the user to the Webauth protected service and allows the service to set a cookie that will be presented on subsequent visits.

When the browser revisits the Webauth protected service the service specific cookie is presented which proves the identity of the user, so no additional authentication steps need to take place.

When a browser visits a second Webauth protected service no service specific cookie is presented so the browser is redirected to the Webauth login server. However, this time the browser presents the cookie previously set by the Webauth login server. This proves the identity of the user to the login server so it can immediately redirect the browser back to the second service along with the additional information required for the second service to set a cookie used for subsequent visits.

Doing all of this securely in a way that no undue trust is placed in the contents of the cookies is where all the devilish details live.



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

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



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:

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:

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.



4. How do I log out of Webauth, or a Webauth enabled application?

It is virtually impossible to provide a logout that will reliably log a user out of all the applications they have logged into. This is because each Webauth enabled web service has a Webauth application cookie scoped to the individual server, and it isn't possible to remove cookies scoped to other servers, as each server can only remove their own cookie. The only way to ensure that a user is completely logged out is for the user to close their browser.

There are four different sets of cookies that have to be removed in order for a user to be completely logged out:

Application specific cookies
These are cookies that the application uses to keep state
Webauth cookies scoped to the server the application is running on
This group of cookies (with names that start with "webauth_") is what the Webauth service running on the local application server makes use of to keep track of users
Main Webauth service cookie
This is the master cookie that the main Webauth service makes use of to issue all the application server scoped Webauth cookies
Webauth cookies for other remote servers
It is impossible for anybody but the servers the cookies are scoped for to remove these cookies, and the only way to be certain these have been removed is for the user to completely close their browser

It is possible for an application to remove its own Webauth cookies, but the best way to do it is to let the Webauth module do it for you. To enable this something similar to the following Apache2 configuration fragments can be used (where the /private location is where your application is normally running):

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

<Location /private/logout>
  WebAuthDoLogout on
</Location>

It's the WebAuthDoLogout on that does the magic and removes the local Webauth cookies. Use this location to remove any application cookies that may be present and then redirect the user to https://webauth.ox.ac.uk/logout. This location will remove the master Webauth cookie and display a message telling the user to close their browser.