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:

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

output = getAttribute(“username”) + “@” + getAttribute(“scope”)

1	output = getAttribute(“username”) + “@” + getAttribute(“scope”)

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:

output = getAttribute(“username”) + “@myinstitution.ac.uk”

1	output = getAttribute(“username”) + “@myinstitution.ac.uk”

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):

<EntityDescriptor entityID=”google.com” xmlns=”urn:oasis:names:tc:SAML:2.0:metadata”>
        <SPSSODescriptor protocolSupportEnumeration=”urn:oasis:names:tc:SAML:2.0:protocol”>
        <NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</NameIDFormat>
        <AssertionConsumerService index=”1″ Binding=”urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST”
                Location=”https://www.google.com/a/myinstitution.ac.uk/acs” />
        </SPSSODescriptor>
</EntityDescriptor>

<NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</NameIDFormat>

<AssertionConsumerService index=“1” Binding=“urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST”

Location=“https://www.google.com/a/myinstitution.ac.uk/acs” />

</SPSSODescriptor>

</EntityDescriptor>

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

Warnings

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.
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.