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.

It is proposed that a connection between Evergreen and OpenAthens can be created at any level in the organisational hierarchy using library settings. This way, a connection could be created for an individual library, a regional library system or for the whole consortium, with settings being inherited down the hierarchy as for other library settings. The choice of where in the hierarchy to create a connection will depend on how the libraries subscribe to the OpenAthens service. If the whole consortium using Evergreen is a single OpenAthens customer sharing a single OpenAthens domain, then the connection would be created at the top level; if only some individual libraries are OpenAthens customers, or each library in a consortium has its own OpenAthens domain, a connection would be created for each library in their own library settings.

For each OpenAthens domain, an administrator will have access to the OpenAthens admin portal, where they can create an Evergreen connection from the OpenAthens side. This process generates a unique connection ID, access URL and API key. They then create an OpenAthens library configuration at the appropriate level within Evergreen, using these credentials.

The OpenAthens portal also allows the administrator to view details of which patrons have signed in, and view statistics around access to third party resources.

The library 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, where administrators can 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 flag within the library settings to enable it if required. The home library attribute would have to be enabled if the librarian wants to use it to map patrons into different sub-organisations within their OpenAthens domain.

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.

A new type of library setting would be created for OpenAthens integration, with the following fields:

• 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 - supported values:
  • 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 - supported values:
  • id (default)
  • usrname
  • fullname (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)

The proposed new URLs are:

• /eg/opac/sso/openathens (protected by OPAC login) - endpoint that establishes OpenAthens session. This would handle both flows (1) and (2) as described above
• /eg/opac/sso/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:

• route the /eg/opac/sso/openathens/* URLs to the new submodule
• intercept the login flow to include a redirect to /eg/opac/sso/openathens if configured to do so
• intercept the logout flow to include a redirect to /eg/opac/sso/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.