From: Andrea Buntz Neiman Date: Fri, 9 Apr 2021 14:46:18 +0000 (-0400) Subject: Docs: Single Sign On X-Git-Url: https://old-git.evergreen-ils.org/?a=commitdiff_plain;h=e1b7cda3eee249c0467110df69968255cafd7f6c;p=evergreen%2Fmasslnc.git Docs: Single Sign On Signed-off-by: Andrea Buntz Neiman Signed-off-by: Galen Charlton --- diff --git a/docs/modules/admin_initial_setup/assets/images/media/sso_and_native.png b/docs/modules/admin_initial_setup/assets/images/media/sso_and_native.png new file mode 100644 index 0000000000..14ade2c525 Binary files /dev/null and b/docs/modules/admin_initial_setup/assets/images/media/sso_and_native.png differ diff --git a/docs/modules/admin_initial_setup/assets/images/media/sso_only.png b/docs/modules/admin_initial_setup/assets/images/media/sso_only.png new file mode 100644 index 0000000000..6c0fd7c143 Binary files /dev/null and b/docs/modules/admin_initial_setup/assets/images/media/sso_only.png differ diff --git a/docs/modules/admin_initial_setup/pages/single_sign_on.adoc b/docs/modules/admin_initial_setup/pages/single_sign_on.adoc new file mode 100644 index 0000000000..c13c1c8712 --- /dev/null +++ b/docs/modules/admin_initial_setup/pages/single_sign_on.adoc @@ -0,0 +1,367 @@ += Single Sign On for Evergreen OPAC +:toc: + +indexterm:[Authentication,Single Sign On,Identity Provider] + +== Introduction + +The Single Sign On mechanism for the Evergreen OPAC adds the ability for +Evergreen to authenticate users against a configurable authoritative +external source, using Shibboleth. + +Single Sign On systems are often used in academic institutions as a way +to authenticate students, faculty, and staff across a wide range of +separate digital services. The goal of a Single Sign On system is to +permit a user to log in with a single set of credentials across all of +these services. Each service talks to an Identity Provider (IdP) which +confirms that a given user is authorized to use the service. For +example, a college might be able to use an IdP to support a single login +which will authenticate a student to the library catalog, the school’s +collection of databases, and internal school services such as the +registrar. + +This feature supports setting up separate Identity Providers within a +single Evergreen instance, and this is controlled via an Apache +VirtualHost configuration which is described in detail below. + +This feature does not offer external authentication for the Evergreen +staff client. + +== Public Catalog Display + +If a location has Single Sign On activated, by default a patron will be +required to authenticate the Single Sign On service. In most cases the +patron will be transparently redirected to the Single Sign On login. +However, if a patron navigates directly to the URL +`+https:///eg/opac/login+`, they will be presented +with a prompt redirecting them to the Single Sign On service: + +image::media/sso_only.png[Redirect to Single Sign On] + +If a location wishes to permit Evergreen-native authentication as well +as Single Sign On authentication, the Library Setting _Allow both +Shibboleth and native OPAC authentication_ should be set to TRUE. In +that case, a patron who navigates to the login page, or to a page +requiring authentication, will see this: + +image:media/sso_and_native.png[Single Sign on and native authentication permitted] + +== Administration + +Single Sign On is controlled by several Evergreen Library Settings, and +an Apache setting. There is one new permission. + +=== Permissions + +Users must have the new SSO_ADMIN permission assigned at the appropriate +working locations and depths in order to set or change any of the below +Library Settings. + +=== Library Settings + +Library settings are inheritable, unless there is an organizationally +closer setting. + +* *Enable Shibboleth SSO for the OPAC* +** TRUE / FALSE +** Controls whether Shibboleth is being used. +* *Allow both Shibboleth and native OPAC authentication* +** TRUE / FALSE +** Default is false, which will redirect patrons to the configured Single +Sign On service. +** If set to true, patrons will still be presented with an Evergreen login +form when Single Sign On is enabled. +* *Log out of the Shibboleth IdP* +** TRUE / FALSE +** Default is false, which will leave a user logged into Shibboleth but +will forget their Evergreen authoken and set a cookie so they are logged +out of Evergreen until they choose to log back in. +** If set to true, the user will be logged out of Shibboleth when they log +out of Evergreen. Additionally, if the IdP implements the +SingleLogoutService option, the user will be logged out of the IdP as +well. +** This setting works on an intentional logout; a timeout behaves +differently (see below). +* *Shibboleth SSO Entity ID* +** Text +** Records which configured Entity ID to use for Single Sign On, if there +are multiple Identity Providers in use by a single Evergreen instance. +* *Evergreen SSO matchpoint* +** Text +** Indicates which field carries the ID that Shibboleth is looking for. +Default is *usrname*, but also accepts *barcode* and *email* (note the +last is not a unique value in Evergreen). +* *Shibboleth SSO matchpoint* +** Text +** Indicates which value is coming from Shibboleth that Evergreen will need +to look up a user. This is defined in the Shibboleth configuration and +defaults to *uid*. + +Note that the existing Library Setting _OPAC Inactivity Timeout_ will +log a user out of Evergreen but not out of Shibboleth. Shibboleth has a +separate configured timeout value. If the user is logged out of +Evergreen due to a timeout, but is still logged in to Shibboleth, they +will be transparently reauthenticated to Evergreen when they select the +*MyAccount* button. + +=== Apache Settings + +In order to identify which location (i.e., Organizational Unit) is used +as the context location for Shibboleth-related library settings, the +*sso_loc* Apache variable can be set. This is configured per hostname in +exactly the same way as the *physical_loc* Apache variable. For example: + +.... + + ... + SetEnv sso_loc 101 + # The following may be necessary based on how Shibboleth is configured + + ShibRequestSetting applicationId otheridp + + ... + +.... + +If *sso_loc* is not set, Evergreen will check for a *physical_loc* +setting, and finally, fall back to the current search library. This +setting is only required if the multiple Identity Providers need to be +supported but the *physical_loc* setting is inappropriate for choosing +the context location. + +=== Shibboleth configuration + +Configuring Shibboleth is particular to each institution's needs, and +depends on the IdP or IdPs that will be used. However, here are a couple sample configurations to use as examples. + +==== Simple configuration that can support multiple IdPs + +.Simple configuration +[source:xml] +.... + + + + + + + + + + + + SAML2 SAML1 + + + + SAML2 Local + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +.... + +==== Configuration to support multiple Evergreen hostnames + +.Configuration for multiple hostnames +[source:xml] +.... + + + + + + + + + + + + + + + + + + + + + SAML2 SAML1 + + + + SAML2 Local + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +.... + +==== Other configuration information + +Some common attribute maps that are useful for Microsoft ActiveDirectory +and UNIX LDAP IdPs that can be added to attribute-map.xml are: + +`++` + +`++` + +`++` + +`++` + +`++` + +For some IdPs, such as SimpleSAMLphp, it can be necessary to add a +special security policy to security-policy.xml: + +[source:xml] +.... + + + +.... + +==== Testing your configuration + +To test if there is a current active Shibboleth session, go here: +`+https:///Shibboleth.sso/Session+` + +For testing purposes, if you need to reset the browser so it’s as if a +user has never logged in before, this can be done by clearing all +cookies associated with the Evergreen OPAC.