LP#1871211: Shibboleth release notes
[Evergreen.git] / docs / RELEASE_NOTES_NEXT / Administration / Shibboleth.adoc
1 Single Sign On (Shibboleth) OPAC integration
2 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3
4 The Evergreen OPAC can now be used as a Service Provider (SP) in a
5 Single Sign On infrastructure.  This allows system administrators to
6 connect the Evergreen OPAC to an identity provider (IdP).  Such a scenario
7 offers significant usability improvements to patrons:
8
9 * They can use the same, IdP-provided login screen and credentials that they
10 use for other applications (SPs).
11 * If they have already logged into another participating application, when
12 they arrive at the Evergreen OPAC, they can be logged in without needing to
13 enter any credentials at all.
14 * Evergreen can be configured to offer a Single Sign-out service, where
15 logging out of the Evergreen OPAC will also log the user out of all other SPs.
16
17 It can also offer security benefits, if it enables a Shibboleth-enabled
18 Evergreen installation to move away from insecure autogenerated user passwords
19 (e.g. year of birth or last four digits of a phone number).
20
21 Different Org Units can use different IdPs.  This development also supports a
22 mix of Shibboleth and non-Shibboleth libraries.
23
24 Note that only the OPAC can be integrated with Shibboleth at this time; no such
25 support exists for the staff client, self-check, etc.
26
27 Also note that this development does not include automatic provisioning of
28 accounts.  At this time, matching accounts must already exist in Evergreen
29 for a patron to successfully authenticate into the OPAC via Single Sign On.
30
31 Installation
32 ++++++++++++
33
34 Installing and configuring Shibboleth support is a complex project.  In
35 broad strokes, the process includes:
36
37 . Installing Shibboleth and the Shibboleth Apache module (`apt install libapache2-mod-shib2` on Debian and Ubuntu)
38 . Configuring Shibboleth, including:
39   * Setting up a certificate
40   * assigning an Entity ID
41   * getting metadata about the IdP from the IdP (perhaps "locally maintained
42   metadata", where an XML file from the IdP is copied into place on your
43   Evergreen server)
44   * Understanding what attributes the IdP will provide about your users,
45   describing those in the `attribute-map.xml` file.
46 . Providing your Entity ID, information about possible bindings, and any
47 other requested information to the IdP administrator.  Much of this information
48 will be available at http://YOUR_EVERGREEN_DOMAIN/Shibboleth.sso/Metadata
49 . Configuring Apache, including:
50   * Enabling shibboleth authentication in the `eg_vhost.conf` file
51   * (Optional) Using the new _sso_loc_ Apache variable to identify
52   which org unit should be used as the context location when fetching
53   Shibboleth-related library settings.
54 . As a user with the new _SSO_ADMIN_ permission, configure Evergreen using
55 the Library Settings Editor, including:
56   * Enable Shibboleth SSO for the OPAC
57   * (Optional) Configure whether you will use SSO exclusively, or offer
58   patrons a choice between SSO and standard Evergreen authentication
59   * (Optional) Configure whether or not you will use Single Log Out
60   * (Optional) In scenarios where a single Evergreen installation is
61   connected to multiple IdPs, assign org units to the relevant IdPs,
62   referenced by the IdP's Entity Id.
63   * Of the attributes defined in `attribute-map.xml`, configure which one
64   should be used to match users in the Evergreen database.  This defaults
65   to uid.
66   * For the attribute you chose in the previous step, configure which
67   Evergreen field it should match against.  Options are usrname (default),
68   barcode, and email.
69
70 This https://www.youtube.com/watch?v=SvppXbpv-5k[video on the SAML protocol] can
71 be very helpful for introducing the basic concepts used in the installation and
72 configuration processes.