skip to primary navigationskip to content
 

Raven for webmasters

The Raven authentication service can be used by any website to authenticate University users, and is easy for webmasters to integrate.

Why use Raven?

The Raven service can be used to authenticate University users by any website. Raven authentication offers several big advantages for University webmasters:

  • No additional User Admin burden for the webmaster – user data is drawn from the central records on Jackdaw
  • Tried and tested solution, in use since 2004
  • Easy integration using either the Ucam-WebAuth protocol plug-in or Shibboleth
  • No need to register your web servers to use it over the Ucam-WebAuth protocol; registration of some technical details is required when using Shibboleth (see below).
  • Raven can pass additional data about the user to your web server
  • Allows your users to connect from outside the CUDN, e.g. from home
  • Uses the CRSids and UIS Passwords already familiar to University staff and students.

Implementation

Web sites can interact with Raven in two ways to authenticate their users: using the Ucam-WebAuth protocol, or using Shibboleth. The two options are described below. The web pages at http://raven.cam.ac.uk/project/ and the wiki at https://wiki.csx.cam.ac.uk/raven/ contain various resources for webmasters and web site managers who are interested in using Raven.

Using Ucam-Webauth

Ucam-WebAuth is the protocol supported by Raven since its launch in 2004 and the one currently used by most Raven-protected web sites in the University. It is often called 'the Raven protocol' or just 'Raven'.

The simplest way to implement Raven authentication using Ucam-Webauth is with a web server 'plug-in'. For example there is an Apache module (mod_ucam_webauth) which allows Raven authentication to be used with Apache version 1 and version 2 web servers. Installing plug-ins is normally fairly straight forward, requiring only a copy of the the plug-in and the current Ucam-WebAuth public keys, together with some configuration, to get it going. To use the jargon of web authentication, these 'plug-in's implement 'container managed security'. This approach is particularly well suited to protecting static documents such as HTML files.

The alternative, which gives more flexibility and access to additional facilities, is 'application managed security'. This involves embedding a Ucam-WebAuth 'Agent' directly into web applications, be they CGI scripts, PHP pages, ASP applications, Java servlets, etc. Libraries implementing Raven authentication for some common web application frameworks (e.g. a JAVA Servlet Library) are available. Details of the Ucam-WebAuth protocol are available, as is an example implementation of a Ucam-WebAuth agent.

Ucam-WebAuth only provides an authenticated CRSid (and, from 2013, optionally an indication if that CRSid corresponds to a current member of the University). Servers or applications are responsible for using this to make authorisation decisions. This could simply be by assuming that anyone with a Raven identity is 'part of the University' which might be satisfactory for some applications. Otherwise it is necessary to look up the CRSid in a list of authorised users, which could be a flat file, a database, an LDAP directory, lookup, etc. This is typically done using the native facilities of a web server in the case of container managed security, for example the 'require' directive in Apache, or with custom code in an application.

For some applications, a mixture of 'container managed' and 'application managed' security may be the simplest to use. Container managed security 'plug-in's typically make information about the authenticated user available so it can be accessed by applications that it protects - for example mod_ucam_webauth makes the authenticated CRSid available in the REMOTE_USER CGI variable. It is therefore possible to leave the Raven interaction to a container managed security 'plug-in' but still to implement access control decisions using custom code in an application.

Using Shibboleth

The Internet2 Shibboleth project created a standardised web authentication and authorisation framework that is being adopted internationally. It is similar to Ucam-WebAuth, but extended to allow users from multiple organisations to authenticate using multiple 'Identity Providers' and to access resources provided by other independent organisations. From October 2007, Raven has supported authenticating University users via Shibboleth.

Unlike Ucam-WebAuth, Shibboleth can also supply information about authenticated users to simplify making authorisation decisions. Within the University, much of this information comes from lookup.

Shibboleth is more complex to deploy on web sites than Ucam-WebAuth. Good reasons for wishing to use Shibboleth include the need to support users from outside the University who can themselves authenticate via Shibboleth, to deploy third-party software that already supports Shibboleth, or to take advantage of the additional authentication information available. Anyone considering deploying Shibboleth should start by reviewing the Shibboleth page in the Raven Wiki.

Privacy and Data Security

Sites using Raven must realise that information provided over Ucam-Webauth or Shibboleth relates to living human beings and as a result anything recorded along with this information will be 'personal data' under the terms of the Data Protection Act 1998. While this does not prevent the data being processed it does impose a number of conditions.

Sites should already have a 'privacy policy' setting out the data that they collect and process about visitors. This should include any data recorded based on identities provided by Raven. Sites should ensure that what they actually do with personal data matches what it says in their privacy policy.

It may be possible to use Raven but to avoid recording information identifying users. For example, an Apache web server will record a user's CRSid in the third field of its 'Access Log' by default. Using the Apache 'LogFormat' directive it is possible to specify this third field as a literal '-', rather than '%u'. This will suppress recording of CRSid while maintaining the file in a format that most web-analysis programs will accept. Note however that CRSid's might still get recorded elsewhere (for example in the 'Error Log') so it may be difficult to completely suppress them, and in any case things like hostnames and IP addresses may also be personal data under some circumstances. Shibboleth also supports the use of 'anonymous' attributes which don't disclose real world identities.

Ucam-WebAuth and Shibboleth 'plug-in's and libraries almost always use HTTP Cookies to manage authentication state. Since 2011, server operators have been required to obtain consent from each end user to set cookies on their devices (see "The Privacy and Electronic Communications (EC Directive) Regulations 2003" as amended by "The Privacy and Electronic Communications (EC Directive) (Amendment) Regulations 2011"). However in some cases it may be sufficient for the server operator to make it clear that they are using cookies and to provide information about what any cookies they use on their sites are doing. At the very least you will need to document the cookies that you use, what data they store and how it is used. Information about the cookies used by the Apache Ucam WebAuth and Shibboleth plugins is available in the Raven wiki.

Contact information

General questions and user queries (including questions about Raven accounts) should be addressed to the  Technical enquiries from webmasters about Raven deployment and use can be sent to 

There are two mailing lists for people interested in Raven:

  • cs-raven-announce which carries announcements about the Raven service and developments and is intended to be low-volume. Anyone using Raven on a web site that they administer should probably be subscribed to this list.
  • cs-raven-discuss which is for discussing use and development of software that interacts with Raven, and of general issues arising from using it.

Follow the links above, or send a message to cs-raven-announce-request@lists.cam.ac.uk or cs-raven-discuss-request@lists.cam.ac.uk with the word 'help' in the subject or body for more information.