ucam-wls: a Raven-like login service library

Documentation [WIP] | PyPI | GitHub

ucam-wls is a Python library to implement the web login service (WLS) component of the 'Ucam-WebAuth' (or 'WAA2WLS') protocol, which is used primarily at the University of Cambridge as part of the Raven authentication service.

---

Introduction

There are many implementations of the 'web authentication agent' (WAA) part of Ucam-WebAuth. These are run by the party that is requesting a user's identity, and they exist already for various platforms, applications and languages.

Examples include:

• the officially-supported mod_ucam_webauth module for Apache Web Server, which is very popular (at least within Cambridge University)
• ucam-webauth-php, also published by the University but "not (officially) supported"
• Daniel Richman's python-ucam-webauth
• django-ucamwebauth, which is written and maintained by a team within the University

(More are listed on the Raven project page.)

However, no known implementations of the WLS component (which authenticates users against known credentials) exist, apart from the official Raven production and test/demo servers.

ucam-wls is a first attempt at a solution for developing your own WLS. It is intended to be easily integrated into a custom or in-house application to provide the full authentication service.

Potential applications

An internal single sign-on service:

• Useful for systems with in-house user account bases: internal webapps avoid reinventing the wheel by using battle-tested WAA implementations.
• Easier to develop an internal login system in this way: half the work (the WAA side) is already done.
• Internal webapps no longer need to roll their own authentication systems/databases, and access to passwords can be kept in a centralised location.
• Sounds a lot like the Raven service, but webapps can authenticate against an entirely different user database.

Two-headed login service:

• Users can authenticate using either locally-administered credentials, or by being 'referred' to Raven (where the WLS redirects the client browser to Raven using the same request parameters).
• Integrates authentication of local guest, external or special (e.g. administrator) accounts with that of mainstream Raven users, creating a unified login process regardless of the 'source' of the user's identity.
• Similar to local vs. Raven login options on many websites and CMSes, but can be managed institution-wide rather than having to maintain decoupled sets of passwords on each installation of WordPress, Drupal, etc.

The above two use-cases essentially offer the same benefits that Raven does, but with the added advantage that users don't need a Raven account to benefit (e.g. guests, external researchers, former staff/alumni). Alternatively, if they do have a Raven account, they can be given the option of using Raven or local credentials.

The next use-case is different...

Stricter authentication requirements than what Raven provides:

• Useful for sensitive applications
• Require both a username/password (possibly from either Raven or local credentials; see above) as well as multi-factor authentication methods such as a one-time password (OTP).
• OTP secrets can be kept and managed centrally; the webapp never sees them or the OTP responses.

Example WLS implementation

A simple implementation of a WLS using this library, and similar in nature to the Raven demo server, is available in the wls-demo repository.

Contributing

There is a long to-do list on this project. It includes:

• Writing unit tests
• Improving API documentation

If you are keen to help out on any of the above (or indeed anything else), then please fork, commit and submit a pull request! Maybe get in touch too :)

A warning

ucam-wls is currently alpha quality software. It has not been tested heavily (yet), so no guarantees can be made regarding its security or robustness.

For example, while the library attempts to make some checks on input arguments (regarding types, values, validity etc.), it is still definitely possible to produce bogus responses that will confuse WAAs. (However, ucam-wls is a library, and there is some level of expectation that application developers will interface with it properly!)

What this library does and doesn't do

ucam-wls is a library, not a complete solution. Accordingly, it will:

• Provide a high-level interface to a protocol-compliant implementation of a WLS.
• Accept authentication requests as URL query strings, a Python dictionary of parameters, or as keyword arguments to a class constructor function.
• Generate signed authentication responses with the appropriate status code, using a provided RSA private key.

But ucam-wls won't:

• Run a fully-blown authentication server that checks usernames/passwords.
• Serve a web interface for users to authenticate. (See wls-demo for an example of this.)
• Manage your RSA private keys for you.

Links

• WAA2WLS protocol definition
• Raven project pages
• Raven wiki. Contains lots of newer information on Raven support, WAA implementations, etc.

Credits and copyright

ucam-wls is authored by Edwin Balani, and released under the terms of the MIT License.

The Ucam-WebAuth/WAA2WLS protocol was designed by Jon Warbrick.