--- /dev/null
+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.
projects / evergreen-equinox.git / commitdiff