Brice Stacey home

Single Sign-On Authentication Using EZProxy UserObjects

Spurred by OCLC's development for WorldCat Local, version 5.1c of EZProxy introduced a new feature called UserObjects. Think of UserObjects as an entity that represents an active session within EZProxy. With some initial configurations and a carefully crafted URL, any 3rd party service can use EZProxy as a means of authentication whereby a library could potentially use EZProxy as a single sign-on service for all library products.

Setting Up EZProxy's config.txt

First and foremost, a couple settings must be made in the config.txt file. To enable UserObjects, include the following.

Option UserObject
Option UserObjectTestMode
LocalWSKey JHjkh234jkh423jkh423jkhjk423hjk423hjkh423jkhK23JHK423JKH4JK23HJK423HJK423HJK423H
RedirectSafe ezproxy.example.com
RedirectSafe www.example.com

The UserObject option enables UserObjects. By default, EZProxy does not provide an interface to easily see the contents of a UserObject. By enabling UserObjectTestMode, you can visit http://ezproxy.example.com/userObject?service=getToken to login and see the UserObject for current user. Once you're done testing, you can remove this, but other steps must be completed first (see: writing a 3rd party application to process EZProxy UserObjects).

The WSKey is a secret key and will be required by 3rd parties to retrieve the actual contents of a given UserObject. More on that later.

You will need to set a RedirectSafe for each hostname that EZProxy automatically redirects users to. You must include the hostname of your EZProxy instance and you will need to include the hostname of the site using EZProxy to authenticate.

Setting Up EZProxy's user.txt

You also need to modify your user.txt file to populate the session namespace with data to appear in the UserObject. There are many ways to do this depending on your authentication scheme. I have already outlined in detail how I configured the user.txt for UMass Boston using SIP. OCLC also has some documentation included in their wiki on WorldCat Navigator.

If you don't already have an authentication scheme configured that populates the session namespace, I suggest using the following for test purposes (copied from OCLC):

If login:user eq "BXL01PAT" && login:pass eq "patron" {
   Set session:uid="BXL01PAT"
   Set session:forename="Patron"
   Set session:surname="Boston College Law Library"
   Set session:[email protected]
   Set session:location="BXL"
   Set session:category=PATRO
   Set session:joinDate=06-09-2009
   Set session:expiryDate=06-09-2010
   Set session:bannedInRemoteCirculation="N"
   Accept
   Stop
}

The provided variables would appear in the UserObject for the user BXL01PAT with a password of patron.

Writing URLs to Use EZProxy as a point of Authentication

First and foremost, any application wishing to use EZProxy UserObjects as a method of authentication will need to be configured to support them. In almost all cases, a custom application will need to be written. I don't know of anyone supporting EZProxy natively, nor anyone really trying to do anything similar.

First, you must create a URL to initiate authentication. The URL looks like so:

https://login.ezproxy.example.com/login?renew=true&amp;url=https://login.ezproxy.example.com/userObject?service=getToken&amp;returnURL=http://www.example.com/ezproxy.php

The URL contains the following parameters:

renew (optional) - If this parameter exists, EZProxy will require the user to login again regardless of an existing session. If this parameter does not exist, EZProxy will reuse an existing session (stored via a cookie). Let me emphasize it again, you cannot disable disable this by setting the value to 0, false, null, or any other value that represent a disabled state. You must simply omit it as a parameter.
url (required) - This should be set to https://login.ezproxy.example.com/userObject?service=getToken where ezproxy.example.com is your EZProxy istance. In my case, our EZProxy SSL Certificate is a wildcard for .ezproxy.example.com. Therefore, it's important that I include the subdomain login in order to prevent browser warnings.
returnURL - This the URL where the user will be redirected if authentication is successful. The UserObject ticket hash is passed to this page via a ticket URL parameter. This page should contain logic to store the ticket, retrieve UserObject data via EZProxy's REST API, and perform necessary operations to validate the user for the given application.

Accessing UserObject Data via EZProxy's REST API

EZProxy provides a secure REST API to access a UserObject's data. You'll notice that I am using the same wskey included in my config.txt I mentioned earlier. This is important, otherwise EZProxy will deny your request. cURL by default fails if it receives any browser warnings. To avoid this, I turn off CURLOPT_SSL_VERIFYPEER.

This script simply retrieves the UserObject and prints it on the screen.

<?php
  $wskey = 'JHjkh234jkh423jkh423jkhjk423hjk423hjkh423jkhK23JHK423JKH4JK23HJK423HJK423HJK423H';
  $url = $_GET['token'] . '&service=getUserObject&wskey=' . $wskey;
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
  curl_setopt($ch, CURLOPT_URL, $url);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

  $o = curl_exec($ch);
  curl_close($ch);
  print $o;
?>

If you were writing an actual authentication extension to an existing product, I would need to use whatever APIs that application provided to create a valid session and populate it with data from the UserObject. This is nothing novel and is exactly the same process required when writing for instance an LDAP extension to an existing product.

So What's the Big Idea?

EZProxy is already a powerful tool for libraries. It's a simple tool for allowing off-campus users access to licensed materials. With UserObjects, EZProxy becomes even more powerful and creates the opportunity of using EZProxy as a single sign-on for all library products. This would dramatically simplify the user experience of a library's electronic services which are often fragmented.

My future plans include supporting EZProxy authentication in Drupal and ILLiad. If you are interested in helping with development, please let me know. I'd love to chat.