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.