wishlist: Single Sign on for Evergreen OPAC

[Andrea Neiman]

This project is sponsored by Linn-Benton Community College and BC Libraries Cooperative.

We will be creating a single sign-on mechanism for the OPAC allowing authentication to happen against a configurable external source.

Availability and parameters of the feature will be controlled by various new library settings.

Full specs can be seen here:
https://yeti.esilibrary.com/dev/public/techspecs/sso_eg.pdf

[Mike Rylander (mrylander)]

Here is a branch implementing Shibboleth-based patron SSO for Evergreen. From the commit message:

This commit adds Shibboleth integration to Evergreen for use in the OPAC. Using Shibboleth, libraries can authenticate patrons against a wide variety of 3rd party services, using many different protocols and standards.

Several settings control if, when and how to make use of the Shibboleth integration:
 * Enable Shibboleth SSO for the OPAC
  - The main on/off switch.
 * Allow both Shibboleth and native OPAC authentication
  - By default only one or the other will be allowed. This enables both native and Shibboleth login.
 * Log out of the Shibboleth IdP
  - If supported by the IdP configured for use on the other side of Shibboleth, this tells Evergreen to tell Shibboleth to log out of the IdP on Evergreen logout.
 * Shibboleth SSO Entity ID
  - If multiple IdPs are configured for Shibboleth, and available to a particular hostname, this setting defines the one to use for a given context org unit.
 * Evergreen SSO matchpoint
  - The Evergreen-side user field to use when looking up the patron after successful SSO login.
 * Shibboleth SSO matchpoint
  - The Shibboleth-side field, defined in the attribute map, that contains the IdP user identifier value used to look up the Evergreen patron.

Two apache sesttings control how Evergreen interacts with Shibboeth:
 * SetEnv sso_loc XXX, which acts in a way analogous to the physical_loc environment variable to define the context OU for SSO settings.
 * ShibRequestSetting applicationId XXX, which helps Shibboleth identify the correct set of entity ID and attribute mapping configuration.

Additional Shibboleth-focused documentation and examples will be provided for system administrators.

https://git.evergreen-ils.org/?p=working/Evergreen.git;a=shortlog;h=refs/heads/user/miker/lp-1871211-Shib-patron-SSO

[Jane Sandberg (sandbergja)]

Thank you, Mike and Andrea. I will note that I tested this as an end-user during the testing phase, and it worked very well! It will be a great improvement for our patrons.

I'm trying to test enabling this feature. Is it assumed that the Evergreen server...
  * have shibd running
  * have the shib2 httpd mod enabled
  * have all possible IdPs listed in an XML file available to shibd (from which you can then select using the library setting)?

Or am I missing something simple?

[Mike Rylander (mrylander)]

Hi Jane,

Yes, that is basically correct. You will need shibd running and the shib2 apache module, however each IdP will have its own metadata XML file and those are described in the main config file using MetadataProvider tags in the main Shibboleth config XML.

The documentation includes example configuration files for Shibboleth that show how to set things up so that different hostnames hosted by one Apache instance can use different IdPs, one for each. There's also a simpler one where there is only one hostname.

Shibboleth configuration can range very simple to extremely complex depending on the IdP requirements, but the two examples should cover most cases. Of note is the RequestMapper section of the (only slightly more) complex example XML, which tells shibd which IdP to use based on the Evergreen hostname that the request is coming from. That, in turn, sets the EntityID for the request, which will then match the appropriate EntityID on the MetadataProvider.

The attribute mapping will likely need to be adjusted, and that is described in the documentation as well.

There are some documented Apache settings that help Evergreen and shibd coordinate which IdP to use, as well.

And, finally, library settings can help Evergreen tell shibd which IdP to use based on the Shibboleth EntityID property in the shibd config file. Settings also tell Evergreen what the attributes are called on both the shibd and Evergreen sides of the conversation.

Does that help?

[Andrea Neiman (aneiman)]

And here is a link to said docs (draft form), for Jane and other testers :)

https://docs.google.com/document/d/1T5UIl6sRid-EHfe4I3OHoE7Od8hQBHluPVua-fR1OoI/edit?usp=sharing

[Jane Sandberg (sandbergja)]

Thanks for the help, Mike and Andrea.

I've been trying to use docker and SimpleSAMLphp to test this out on my personal laptop. It's going okay, but I'm getting an endless redirect when following this procedure: http://paste.evergreen-ils.org/10112

Hopefully I'll be able to spend a little bit more time on this soon.

[Christine Burns (christine-burns)]

I have tested this code and consent to signing off on it with my name, Christine Burns and my email address, <email address hidden>.

[Jane Sandberg (sandbergja)]

This is working for me. Thanks a ton to Mike for helping to troubleshoot my testing setup!! Signoff branch here: user/sandbergja/lp-1871211-Shib-patron-SSO

We will need some release notes. Otherwise, I feel comfortable merging in this feature for 3.7. I'll let this marinate for a few days, and then do so, unless it would be better for another committer to commit this (since my college was one of the funders for this project).

If others want to test using docker, feel free to use these updated instructions as a starting point: https://gist.github.com/sandbergja/ef06104e0d63c0b5ddedb912f3458a11

As far as documentation, I think the Equinox documentation is a great starting place, but I'm hoping that after this feature is merged, we can include some detailed, step-by-step instructions for sysadmins who know Evergreen, but are new to Shibboleth.

[Jane Sandberg (sandbergja)]

Added to master for inclusion in 3.7. Thanks so much for your incredible work on this project, Mike and Christine!

I added a follow-up bug here, to get this added to the bootstrap OPAC: bug 1917083