From e7aa5f824c96bcbf5a3bbc2c14a30098264d5aed Mon Sep 17 00:00:00 2001 From: Jane Sandberg Date: Fri, 26 Feb 2021 11:11:35 -0800 Subject: [PATCH] LP#1871211: Shibboleth release notes Signed-off-by: Jane Sandberg --- .../Administration/Shibboleth.adoc | 72 ++++++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 docs/RELEASE_NOTES_NEXT/Administration/Shibboleth.adoc diff --git a/docs/RELEASE_NOTES_NEXT/Administration/Shibboleth.adoc b/docs/RELEASE_NOTES_NEXT/Administration/Shibboleth.adoc new file mode 100644 index 0000000000..6ab54b8bf5 --- /dev/null +++ b/docs/RELEASE_NOTES_NEXT/Administration/Shibboleth.adoc @@ -0,0 +1,72 @@ +Single Sign On (Shibboleth) OPAC integration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The Evergreen OPAC can now be used as a Service Provider (SP) in a +Single Sign On infrastructure. This allows system administrators to +connect the Evergreen OPAC to an identity provider (IdP). Such a scenario +offers significant usability improvements to patrons: + +* They can use the same, IdP-provided login screen and credentials that they +use for other applications (SPs). +* If they have already logged into another participating application, when +they arrive at the Evergreen OPAC, they can be logged in without needing to +enter any credentials at all. +* Evergreen can be configured to offer a Single Sign-out service, where +logging out of the Evergreen OPAC will also log the user out of all other SPs. + +It can also offer security benefits, if it enables a Shibboleth-enabled +Evergreen installation to move away from insecure autogenerated user passwords +(e.g. year of birth or last four digits of a phone number). + +Different Org Units can use different IdPs. This development also supports a +mix of Shibboleth and non-Shibboleth libraries. + +Note that only the OPAC can be integrated with Shibboleth at this time; no such +support exists for the staff client, self-check, etc. + +Also note that this development does not include automatic provisioning of +accounts. At this time, matching accounts must already exist in Evergreen +for a patron to successfully authenticate into the OPAC via Single Sign On. + +Installation +++++++++++++ + +Installing and configuring Shibboleth support is a complex project. In +broad strokes, the process includes: + +. Installing Shibboleth and the Shibboleth Apache module (`apt install libapache2-mod-shib2` on Debian and Ubuntu) +. Configuring Shibboleth, including: + * Setting up a certificate + * assigning an Entity ID + * getting metadata about the IdP from the IdP (perhaps "locally maintained + metadata", where an XML file from the IdP is copied into place on your + Evergreen server) + * Understanding what attributes the IdP will provide about your users, + describing those in the `attribute-map.xml` file. +. Providing your Entity ID, information about possible bindings, and any +other requested information to the IdP administrator. Much of this information +will be available at http://YOUR_EVERGREEN_DOMAIN/Shibboleth.sso/Metadata +. Configuring Apache, including: + * Enabling shibboleth authentication in the `eg_vhost.conf` file + * (Optional) Using the new _sso_loc_ Apache variable to identify + which org unit should be used as the context location when fetching + Shibboleth-related library settings. +. As a user with the new _SSO_ADMIN_ permission, configure Evergreen using +the Library Settings Editor, including: + * Enable Shibboleth SSO for the OPAC + * (Optional) Configure whether you will use SSO exclusively, or offer + patrons a choice between SSO and standard Evergreen authentication + * (Optional) Configure whether or not you will use Single Log Out + * (Optional) In scenarios where a single Evergreen installation is + connected to multiple IdPs, assign org units to the relevant IdPs, + referenced by the IdP's Entity Id. + * Of the attributes defined in `attribute-map.xml`, configure which one + should be used to match users in the Evergreen database. This defaults + to uid. + * For the attribute you chose in the previous step, configure which + Evergreen field it should match against. Options are usrname (default), + barcode, and email. + +This https://www.youtube.com/watch?v=SvppXbpv-5k[video on the SAML protocol] can +be very helpful for introducing the basic concepts used in the installation and +configuration processes. -- 2.11.0