Monthly Archives: December 2012

SSO with Google Apps and OpenAthens LA

Google Apps SAML SSO configuration isn’t the most flexible thing in the world, but it does work.

Google requires that you pass a value to it encoded as a SAML NameID which matches the full email address of the user who has logged in. If you are used to working with SSO in an education context, this concept is unusual, as normally you would pass any required information through in attributes defined by the eduPerson schema.

Shibboleth IdP gives very fine grained control over how to give Google what it needs as you are editing the configuration XML files directly (see this guide from USC for configuring Shibboleth). But in OpenAthens LA we are restricted to using the configuration console to set things up. It can be done quite easily, but please see the warning at the end, as there is a potential side-effect.

This guide applies to version 2.1 and 2.2 of OpenAthens LA, I don’t know about earlier versions.

For the most part, the guide on the Eduserv site is what you need to do, but I would suggest a couple of modifications:

Email address attribute

You need to have an attribute that matches the google email address of the user. You may already have this available in the attribute store (as the Eduserv guide assumes), but if not, it is possible that you have the component parts of the email address available as individual attributes already. For example, if the required format is username@myinstitution.ac.uk  you may have the username already available in an attribute called “username”, and the domain name already available in an attribute called “scope”. If so, you can create a scripted attribute that puts these parts together:

  1. On the Attributes tab, click Add -> Scripted.
  2. Give it a Target Name, I suggest something like GoogleAppsNameID
  3. Assign it to the relevant user categories, probably just Everyone.
  4. In the JavaScript box, enter the following fragment of code, replacing username and scope for your existing attribute names:

If you don’t have a scope attribute, you could always hard code it along with the @ symbol, but obviously hard coding isn’t usually a great idea:

SAML NameID vs User Identifier

One of the steps in the Eduserv guide is to go to the Advanced Options tab and set your email address attribute as the value in the “User Identifier” box.

It seems to be that this is the user-friendly way Eduserv have given us of setting an attribute to be the SAML NameID ( urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified ). Doing some testing, it appears that the the value in urn:oasis:names:tc:SAML:2.0:nameid-format:persistent  is always sent though as whichever attribute you have set up with the special type of “TargetedID” in the admin console.

Google Apps metadata

Eduserv have provided a quick way to add the required Google metadata using the admin console. It constructs a URL which when called generates the metadata with your organisation’s name filled in. It’s quite a nice thing for them to have provided, but due to a bug I have experienced where the IdP refuses to start if the URL is not accessible, I prefer to take the approach of putting the metadata files locally on the server.

So, on OALA 2.2, create a file  /usr/share/atacama-platform/metadata/google_apps_metadata.xml  with the following content (your google apps domain substituted, obviously):

You’ll need to restart the runtime in order for it to pick up the new metadata file.

Warnings

  1. The User Identifier setting is a global one rather than being set in the Attribute Policy for the Google Apps SP. This means if you come across another SP which requires the SAML 1.1 NameID to be something different to the format Google is using, you’ll be stuck. For many this won’t be an issue, however it is something to bear in mind.
  2. I already had an attribute set up which matched the format Google required (eduPersonPrincipalName), so I assumed I could just set this as the User Identifier. It did work, but I found that the eduPersonPrincipalName attribute was no longer being passed as an attribute to service providers. It seems that setting an attribute as the User Identifier removes it from the pool of “normal” named attributes that will be sent.

Enabling Shibboleth WAYFless linking with ExLibris SFX

SFX is an OpenURL link resolver, used in many university library systems. I am no librarian, but my basic understanding is that it takes information about publications (ebooks, journal articles etc) along with information about how your institution should link to said resources (if it subscribes to them), and constructs hyperlinks based on the information. The links appear in places such as library catalogue systems, Google Scholar, and when viewing references and citations sections.

The default settings will lead to the following typical scenario:

  1. Search your library system or Google Scholar for a topic
  2. Click on the search result for the article you are interested in
  3. Arrive on the publisher website at the correct article
  4. You are not logged in so can only see the abstract and a “purchase” button.
  5. Go through a process of varying convolutedness to sign in using e.g. Athens or Shibboleth
  6. Invariably, you are returned to the website homepage, not the article you require, so start your search again and click on the relevant result
  7. Arrive at the page for the article where you have access to the full text

For some major publishers, it is easy to configure SFX to generate links that will take you straight from step 2 to step 7:

Set up your SAML Identity Provider (IdP) details

You set up the Shibboleth IdP details in a text file on the server. These are then used throughout the SFX installation, so you don’t need to set them in multiple places.

Go to your SFX config directory and edit the file shibboleth.config

Find the variable idp_url and set it to be the URL which will handle the single sign on requests. So for a Shibboleth IdP it might be something like this:

Or for OpenAthens LA it would be:

Then, set the entityID parameter, e.g.:

Enable the resources you wish to integrate single sign on for

  1. Log into the SFX KBManager
  2. Under “Linking Parameters” tab, search for the target name you are interested in. The parameter name will be called $$SHIBBOLETH. The target source will usually be called something with “-getFullText” appended at the end.
  3. Click on the “E” button to edit the linking parameter
  4. Enter “yes” (without quotes) in the text box labelled “Value”

That’s it. The final screen should look something like this:

sfx

Now when you click on a link to get the full text for a search result provided by that target, you will be routed via your IdP where you will be asked to sign in if you’ve not previously, and then taken straight to the article page, logged in.