Authentication middle-ware for raven, the authentication provider for cam.ac.uk


This module handles raven authentication for connect web-applications. You might want to use this if you are developing web-apps for use within the University of Cambridge.

var raven = require('raven-auth');
var connect = require('connect');
var routes = function(reqresnext) {
    res.setHeader("Content-Type", "text/plain");
    res.write("Hello, " + req.session.principal);
// Your raven configuration here... 
var conf = {
    logOutPath: '/logout', // If you want to provide log-out as well as log-in 
    localHost: 'http://i.am.here',
    keyStore: '/path/to/where/my/keys/are' // Or a function of type: (string) -> string 
var app = connect()
    .use(connect.cookieParser())           // If using cookies for sessions. 
    .use(connect.session({secret: 'foo'})) // Or any API compatible session library. 

Install from npm

npm install --save raven-auth

Or point at github directly (note that you must include a version ref to get a usable package):

npm install --save git://github.com/alexkalderimis/raven-auth.git#0.0.1

This middleware can be used with any connect-style application system, such as express. This authentication provider does not require any larger authentication framework, and does not validate the principal provided by the authentication service, delegating that service to your own middleware. It has a runtime requirement on parsing of the query-string, and a session api which is compatible with the connect session mechanism (ie. it must provide a session property on the request object which has a #destroy() method). Other than that setting up authentication is fairly straightforward:

Define your configuration options (the defaults are shown below):

var conf = {
  localHost: 'http://i.am.here', // [required = !] Absolute url of the site requesting authentication 
  keyStore: '/path/to/where/my/keys/are', // [!] Or a function of type: (string) -> string 
  logOutPath: '/logout', // [optional = ?] if provided then raven will log users out locally and remotely. 
  ravenUrl: 'http://a.raven.compatible.wls/auth/authenticate.html', // [?] set which raven to use 
  ravenLogOut: 'http://a.raven.compatible.wls/auth/logout.html', // [?] if handling log-out 
  timeout: 60000, // [?] Users must re-authenticate if in-active for this length of time (ms) 
  maxSessionLife: (24 * 60 * 60 * 1000), // [?] Cookie expiries are set for this at a minimum (ms) 
  ver: 2, // [?] The version of the raven protocol we expect 
  maxSkew: 1000, // [?] The maximum allowable difference in clocks between servers (ms) 
  authTypes: ['pwd'] // [?] The acceptable kinds of authentication the server can perform 

Then the middle ware can be applied to the application (note that it must be applied after any of its run-time requirements).

For a global scope:

var connect = require('connect');
var raven = require('raven-auth');
var app = connect()
    .use(connect.bodyParser())             // If you accept post parameters 
    .use(connect.query())                  // Required - for parsing authentication responses 
    .use(connect.cookieParser())           // If using cookies for sessions. 
    .use(connect.session({secret: 'foo'})) // Or any API compatible session library. 

If you are using express, you can protect just some resources:

var express = require('express');
var raven = require('raven-auth')(conf);
app = express();
app.get('/', raven, function(reqres) {
    res.write('A little birdy tells me you are ' + req.session.principal);

npm test will run the test-suite, and npm start will start the test application. These require that the dev dependencies are installed. Running the start command with REAL_RAVEN=1 will use the main raven authenticator as the WLS, so you will need to fetch the keys, which may be done with grunt fetch-keys.

Oddly enough, this isn't even the only node.js raven-autentication package. I went to add this to the wiki and saw https://github.com/ForbesLindesay/passport-raven already on there, completely independently developed. So a brief listing of differences seems in order:

In favour of this libary:

  • Is pure connect middle-ware, and not part of a larger authentication framework.
  • Has a unit-test suite, as a well as a test-server.

In favour of passport-raven:

  • Is part of a larger authentication framework
  • Is developed by a rather bigger js fish (ForbesLindesay) than me.

The libraries have different open-source licences.

I haven't tested passport-raven, but it looks all-good; so both should work fine (I know this one does).

This software is free and open source under the LGPL (see LICENCE.txt)

The copyright on this work belongs to Alex Kalderimis.

Support may be requested by submitting issues to the github bug tracker (https://github.com/alexkalderimis/raven-auth/issues).