Evergreen DokuWiki

This is a feature proposal for integration of Evergreen into the OpenAthens single sign-on service.

The GALILEO Consortium of libraries in Georgia has selected OpenAthens to deliver a state-wide solution for single sign-on, and this contract includes integrating Evergreen, used by the Georgia Public Library Service, into OpenAthens.

This feature proposal is to implement OpenAthens integration for Evergreen, so that Evergreen patrons can seamlessly access OpenAthens-authenticated resources. The OpenAthens team has committed to implementing this feature on behalf of GPLS and contributing it back to the Evergreen community for others to use.

OpenAthens is a cloud-based single sign-on service with a global customer base of libraries and content publishers. Libraries use OpenAthens to authenticate their users into online resources. Librarians can choose to manage user accounts in the cloud on OpenAthens or link their own library system or other user directory with OpenAthens. In this second case, selected by GALILEO, users are automatically assigned an OpenAthens identity dynamically based on their local system login, and do not need accounts created manually in OpenAthens. They can then access online resources that support OpenAthens authentication and to which their library has subscribed. OpenAthens manages the mapping of user identities end-to-end from the local system to the online resource.

OpenAthens Local Directory Integration can be achieved by programming against the OpenAthens API within the Evergreen OPAC code. When Evergreen wants to authenticate a patron into OpenAthens it makes an API call to OpenAthens with details about the patron and receives back a single-use URL. When the user's browser is redirected to this URL, an OpenAthens identity is created and a session established. The OpenAthens API and how to use it in this way is documented at http://docs.openathens.net/display/public/MD/Implementing+the+API+connector+in+your+code

There are two user sign-on flows that would be supported:

1. Resource-initiated sign-on. A user arrives at an online resource that supports OpenAthens authentication without already having an OpenAthens login session. In this case, they would follow that online resource's login process, and choose login via OpenAthens and/or select their library consortium from a list of available options. (The exact user experience differs depending on the resources publisher's implementation.) Once they have selected their consortium, OpenAthens knows that it must delegate the login process to that consortium's Evergreen system. The user is redirected to an OpenAthens-specific endpoint within Evergreen, which is protected by OPAC login, prompting the user to log in with their patron account if they are not already logged in. After Evergreen login, the OpenAthens-specific endpoint will redirect the user back to a URL on OpenAthens that will establish their identity and session, and in turn redirect them back to the online resource. This flow is required for OpenAthens to function correctly and will always be enabled.
2. Locally initiated sign-on. A user starts from Evergreen and logs in with their patron account. The login process is intercepted to redirect the user to an OpenAthens-specific endpoint within Evergreen. This endpoint makes an API call to OpenAthens and redirects the user to a URL on OpenAthens that will establish their identity and session, and then return them back to the My OPAC home page. This interaction should be transparent to the user. This flow would be optional. It generally provides patrons with simpler access the first time they access a resource if they already have an OpenAthens session, so it would be enabled by default. There would be a configuration option to allow the system administrator to disable it if they find a reason to do so.

In either case, when the user subsequently visits OpenAthens-authenticated resources, they would simply need to select OpenAthens login and/or their library consortium name, in order to be logged in via their existing OpenAthens session. It's analogous to selecting Facebook or Google login when visiting a new website that supports it, assuming you are already logged in to Facebook/Google.

There would also be a new OpenAthens logout URL within Evergreen, which would forward the user to the OpenAthens sign-out page. There would be a system-wide setting that determines whether or not this logout URL is called after OPAC logout. OpenAthens in turn can be configured to send users to any URL after logout, so this can be used to return users back to the OPAC home page after their OpenAthens session has been cleared down.

OpenAthens will provide a top-level administrator account for a consortium to use to manage everything connected with its own private domain within the OpenAthens service. The person using this account would be the Evergreen top-level system administrator. They will use this account to configure the Evergreen connection from the OpenAthens side. This process generates a unique connection ID, access URL and API key. They then enter these credentials into OpenAthens-specific global settings within Evergreen. This configuration would be global for the whole Evergreen installation, and so would appear under global flags. A single Evergreen install would only support one connection into a single OpenAthens domain. However, see 'Organisational hierarchy' below.

In the same way as Evergreen supports a hierarchy of regional library systems and branches, OpenAthens can be configured with an arbitrary hierarchy of virtual organisations within a consortium's domain. The top-level OpenAthens administrator for the consortium would build a hierarchy within OpenAthens that matches their library branch hierarchy. It would then be possible to configure OpenAthens to map patrons into different virtual organisations depending on their Evergreen organisational unit attribute. OpenAthens already supports this kind of organisational mapping, so there is no need to develop it within Evergreen as part of this feature.

The top-level administrator would create lower-level OpenAthens administrator accounts for librarians in each region or branch as required. Librarians in each region or branch could use this account to configure a different set of OpenAthens resources for their patrons, depending on their locally purchased resource subscriptions. They could also use it to view account usage and resource access statistics just for their own patrons.

The Evergreen system administrator will be able to configure which user attributes are released to OpenAthens, according to their own data protection policy. For example, they could allow the user's given name to be released, but not their family name or email address. Or they could choose not to release any personal details at all. By default, only a single unique user identifier would be released. OpenAthens uses this identifier to create a unique identity for each user that is passed to third party resources. This is so that the resource can uniquely identify each user and allow them to save preferences, reading lists, etc., even if it does not know their name.

OpenAthens requires two user attributes, but by default both would be satisfied by the numerical database id of the user account.

• Unique identifier - this should be unique to each user and should not change for the duration of the user’s account. The unique identifier is used by OpenAthens to build the unique identity of each user that is passed to third party resources. By default, Evergreen would use the numerical database id of the user account for this. The system administrator could change it to use the username, on the understanding that this would only be sensible if users’ usernames are never changed. Otherwise if a user’s username is changed when they change their family name for example, this would change their OpenAthens identity and they would lose their previous personal preferences saved on third party resources. Using the numerical database id prevents this because it cannot change.
• Display name - this is used only within the OpenAthens administrator’s portal to allow administrators to view virtual accounts that have been created and how they have been used. It is not passed to third party resources. By default, this would also be populated with the numerical database id of the user account, but the system administrator could change it to use the username, or the calculated full name in the same format as displayed in Evergreen. If the chosen attribute of the user is changed in Evergreen it will also change in OpenAthens the next time they sign in, but this will not affect their personalised settings on third party resources.

Other user attributes, such as first name, family name, email address, and home library would not be released by default. Each one would have a global configuration setting to enable it if required.

Regardless of which attributes are released from Evergreen to OpenAthens, OpenAthens will not release them onwards to third party resources unless it is also configured to do so.

All OpenAthens-specific configuration settings would be system-wide. The following would be added to global_flags, in a new 'openathens' namespace:

• disable/enable OpenAthens integration completely (default false)
• OpenAthens API key
• OpenAthens API endpoint URL
• OpenAthens connection ID
• auto-signon - whether to sign patrons into OpenAthens automatically after Evergreen login (flow 2 above) (default true)
• auto-signout - whether to send patrons to the OpenAthens sign-out page after Evergreen logout (default false)
• unique identifier - which attribute of the patron’s account to use as the unique identifier within OpenAthens - options available:*
  • id (default)
  • usrname
• display name - which attribute of the patron’s account to use as the display name for the account within OpenAthens - this will not be released to third party resources - options available:*
  • id (default)
  • usrname
  • full name (as displayed in OPAC header)
• release title - whether to release the patron’s title to OpenAthens (default false)
• release first name - whether to release the patron's first name / preferred first name to OpenAthens (default false)
• release middle name - whether to release the patron's middle name / preferred middle name to OpenAthens (default false)
• release family name - whether to release the patron's family name / preferred family name to OpenAthens (default false)
• release suffix - whether to release the patron’s suffix / preferred suffix to OpenAthens (default false)
• release email - whether to release the patron's email address to OpenAthens (default false)
• release organisational unit - whether to release the patron's home library to OpenAthens (default false)

*Further research is needed to confirm whether global flags can include selectable options, or whether these would need additional database tables.

The proposed new URLs are:

• /eg/opac/openathens/sso (protected by OPAC login) - endpoint that establishes OpenAthens session. This would handle both flows (1) and (2) as described above
• /eg/opac/openathens/logout - this would redirect to the OpenAthens sign-out page.

Neither of these would serve any content; they would only ever issue temporary redirects.

OpenAthens-specific code would be a new submodule of the EGCatLoader Perl module, to be created at:

~/Open-ILS/src/perlmods/lib/OpenILS/WWW/EGCatLoader/OpenAthens.pm

There would need to be a small set of modifications to the core of EGCatLoader.pm to:

• load the OpenAthens configuration settings
• route the /eg/opac/openathens/* URLs to the new submodule
• intercept the login flow to include a redirect to /eg/opac/openathens/sso if configured to do so
• intercept the logout flow to include a redirect to /eg/opac/openathens/logout if configured to do so

This feature would contribute a new page to the Evergreen docs. This page would explain how to create a connection between Evergreen and OpenAthens in the OpenAthens portal, and how to configure the corresponding global flags in Evergreen. It would also give helpful pointers to OpenAthens documentation that explains how to release selected user attributes to third party resources.

Part of the OpenAthens sign-on process involves making an API call directly from the library system to OpenAthens. This API call does not go through the user's browser because it contains system-wide credentials. So there is a requirement for the Evergreen install to be able to make outgoing network requests on port 443 to https://login.openathens.net. This requirement will be added to the Evergreen system requirements documentation.