docs/modules/admin_initial_setup/pages/single_sign_on.adoc

   1 = Single Sign On for Evergreen OPAC
   2 :toc:
   3
   4 indexterm:[Authentication,Single Sign On,Identity Provider]
   5
   6 == Introduction
   7
   8 The Single Sign On mechanism for the Evergreen OPAC adds the ability for
   9 Evergreen to authenticate users against a configurable authoritative
  10 external source, using Shibboleth.
  11
  12 Single Sign On systems are often used in academic institutions as a way
  13 to authenticate students, faculty, and staff across a wide range of
  14 separate digital services. The goal of a Single Sign On system is to
  15 permit a user to log in with a single set of credentials across all of
  16 these services. Each service talks to an Identity Provider (IdP) which
  17 confirms that a given user is authorized to use the service. For
  18 example, a college might be able to use an IdP to support a single login
  19 which will authenticate a student to the library catalog, the school’s
  20 collection of databases, and internal school services such as the
  21 registrar.
  22
  23 This feature supports setting up separate Identity Providers within a
  24 single Evergreen instance, and this is controlled via an Apache
  25 VirtualHost configuration which is described in detail below.
  26
  27 This feature does not offer external authentication for the Evergreen
  28 staff client.
  29
  30 == Public Catalog Display
  31
  32 If a location has Single Sign On activated, by default a patron will be
  33 required to authenticate the Single Sign On service. In most cases the
  34 patron will be transparently redirected to the Single Sign On login.
  35 However, if a patron navigates directly to the URL
  36 `+https://<your.evergreen.domain>/eg/opac/login+`, they will be presented
  37 with a prompt redirecting them to the Single Sign On service:
  38
  39 image::media/sso_only.png[Redirect to Single Sign On]
  40
  41 If a location wishes to permit Evergreen-native authentication as well
  42 as Single Sign On authentication, the Library Setting _Allow both
  43 Shibboleth and native OPAC authentication_ should be set to TRUE. In
  44 that case, a patron who navigates to the login page, or to a page
  45 requiring authentication, will see this:
  46
  47 image:media/sso_and_native.png[Single Sign on and native authentication permitted]
  48
  49 == Administration
  50
  51 Single Sign On is controlled by several Evergreen Library Settings, and
  52 an Apache setting. There is one new permission.
  53
  54 === Permissions
  55
  56 Users must have the new SSO_ADMIN permission assigned at the appropriate
  57 working locations and depths in order to set or change any of the below
  58 Library Settings.
  59
  60 === Library Settings
  61
  62 Library settings are inheritable, unless there is an organizationally
  63 closer setting.
  64
  65 * *Enable Shibboleth SSO for the OPAC*
  66 ** TRUE / FALSE
  67 ** Controls whether Shibboleth is being used.
  68 * *Allow both Shibboleth and native OPAC authentication*
  69 ** TRUE / FALSE
  70 ** Default is false, which will redirect patrons to the configured Single
  71 Sign On service.
  72 ** If set to true, patrons will still be presented with an Evergreen login
  73 form when Single Sign On is enabled.
  74 * *Log out of the Shibboleth IdP*
  75 ** TRUE / FALSE
  76 ** Default is false, which will leave a user logged into Shibboleth but
  77 will forget their Evergreen authoken and set a cookie so they are logged
  78 out of Evergreen until they choose to log back in.
  79 ** If set to true, the user will be logged out of Shibboleth when they log
  80 out of Evergreen. Additionally, if the IdP implements the
  81 SingleLogoutService option, the user will be logged out of the IdP as
  82 well.
  83 ** This setting works on an intentional logout; a timeout behaves
  84 differently (see below).
  85 * *Shibboleth SSO Entity ID*
  86 ** Text
  87 ** Records which configured Entity ID to use for Single Sign On, if there
  88 are multiple Identity Providers in use by a single Evergreen instance.
  89 * *Evergreen SSO matchpoint*
  90 ** Text
  91 ** Indicates which field carries the ID that Shibboleth is looking for.
  92 Default is *usrname*, but also accepts *barcode* and *email* (note the
  93 last is not a unique value in Evergreen).
  94 * *Shibboleth SSO matchpoint*
  95 ** Text
  96 ** Indicates which value is coming from Shibboleth that Evergreen will need
  97 to look up a user. This is defined in the Shibboleth configuration and
  98 defaults to *uid*.
  99
 100 Note that the existing Library Setting _OPAC Inactivity Timeout_ will
 101 log a user out of Evergreen but not out of Shibboleth. Shibboleth has a
 102 separate configured timeout value. If the user is logged out of
 103 Evergreen due to a timeout, but is still logged in to Shibboleth, they
 104 will be transparently reauthenticated to Evergreen when they select the
 105 *MyAccount* button.
 106
 107 === Apache Settings
 108
 109 In order to identify which location (i.e., Organizational Unit) is used
 110 as the context location for Shibboleth-related library settings, the
 111 *sso_loc* Apache variable can be set. This is configured per hostname in
 112 exactly the same way as the *physical_loc* Apache variable. For example:
 113
 114 ....
 115 <VirtualHost *:443>
 116   ...
 117     SetEnv sso_loc 101
 118   # The following may be necessary based on how Shibboleth is configured
 119   <Location />
 120     ShibRequestSetting applicationId otheridp
 121   </Location>
 122   ...
 123 </VirtualHost>
 124 ....
 125
 126 If *sso_loc* is not set, Evergreen will check for a *physical_loc*
 127 setting, and finally, fall back to the current search library. This
 128 setting is only required if the multiple Identity Providers need to be
 129 supported but the *physical_loc* setting is inappropriate for choosing
 130 the context location.
 131
 132 === Shibboleth configuration
 133
 134 Configuring Shibboleth is particular to each institution's needs, and
 135 depends on the IdP or IdPs that will be used. However, here are a couple sample configurations to use as examples.
 136
 137 ==== Simple configuration that can support multiple IdPs
 138
 139 .Simple configuration
 140 [source:xml]
 141 ....
 142 <SPConfig xmlns="urn:mace:shibboleth:2.0:native:sp:config"
 143     xmlns:conf="urn:mace:shibboleth:2.0:native:sp:config"
 144     xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
 145     xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
 146     xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
 147     clockSkew="180">
 148
 149     <!-- The ApplicationDefaults element is where most of Shibboleth's SAML bits are defined. -->
 150     <ApplicationDefaults entityID="https://<your.evergreen.domain>/eg/opac/"
 151                          REMOTE_USER="eppn persistent-id targeted-id"
 152                          cipherSuites="ECDHE+AESGCM:ECDHE:!aNULL:!eNULL:!LOW:!EXPORT:!RC4:!SHA:!SSLv2">
 153
 154         <!--
 155         Controls session lifetimes, address checks, cookie handling, and the protocol handlers.
 156         You MUST supply an effectively unique handlerURL value for each of your applications.
 157         The value defaults to /Shibboleth.sso, and should be a relative path, with the SP computing
 158         a relative value based on the virtual host. Using handlerSSL="true", the default, will force
 159         the protocol to be https. You should also set cookieProps to "https" for SSL-only sites.
 160         Note that while we default checkAddress to "false", this has a negative impact on the
 161         security of your site. Stealing sessions via cookie theft is much easier with this disabled.
 162         -->
 163         <Sessions lifetime="28800" timeout="3600" relayState="ss:mem"
 164                   checkAddress="false" handlerSSL="true" cookieProps="https">
 165
 166
 167             <!--
 168             By not supplying an entity here, Evergreen is required to specify the entity.
 169             This is controlled by the opac.login.shib_sso.entityId YAOUS.
 170             -->
 171             <SSO>
 172               SAML2 SAML1
 173             </SSO>
 174
 175             <!-- SAML and local-only logout. -->
 176             <Logout>SAML2 Local</Logout>
 177
 178             <!-- Extension service that generates "approximate" metadata based on SP configuration. -->
 179             <Handler type="MetadataGenerator" Location="/Metadata" signing="false"/>
 180
 181             <!-- Status reporting service. -->
 182             <Handler type="Status" Location="/Status" acl="127.0.0.1 ::1"/>
 183
 184             <!-- Session diagnostic service. -->
 185             <Handler type="Session" Location="/Session" showAttributeValues="false"/>
 186
 187             <!-- JSON feed of discovery information. -->
 188             <Handler type="DiscoveryFeed" Location="/DiscoFeed"/>
 189
 190             <md:SingleLogoutService Location="/SLO/Redirect" conf:template="bindingTemplate.html"
 191                     conf:policyId="unsigned-slo" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"/>
 192
 193         </Sessions>
 194
 195         <!--
 196         Allows overriding of error template information/filenames. You can
 197         also add attributes with values that can be plugged into the templates.
 198         -->
 199         <Errors supportContact="root@localhost"
 200             helpLocation="/about.html"
 201             styleSheet="/shibboleth-sp/main.css"/>
 202
 203         <!-- Example of locally maintained metadata. -->
 204         <MetadataProvider type="XML" validate="true" file="/etc/shibboleth/simplesaml-idp-metadata.xml"/>
 205         <MetadataProvider type="XML" validate="true" file="/etc/shibboleth/other-external-idp-metadata.xml"/>
 206
 207         <!-- Map to extract attributes from SAML assertions. -->
 208         <AttributeExtractor type="XML" validate="true" reloadChanges="false" path="attribute-map.xml"/>
 209
 210         <!-- Use a SAML query if no attributes are supplied during SSO. -->
 211         <AttributeResolver type="Query" subjectMatch="true"/>
 212
 213         <!-- Default filtering policy for recognized attributes, lets other data pass. -->
 214         <AttributeFilter type="XML" validate="true" path="attribute-policy.xml"/>
 215
 216         <!-- Simple file-based resolver for using a single keypair. -->
 217         <CredentialResolver type="File" key="sp-key.pem" certificate="sp-cert.pem"/>
 218
 219     </ApplicationDefaults>
 220
 221     <!-- Policies that determine how to process and authenticate runtime messages. -->
 222     <SecurityPolicyProvider type="XML" validate="true" path="security-policy.xml"/>
 223
 224     <!-- Low-level configuration about protocols and bindings available for use. -->
 225     <ProtocolProvider type="XML" validate="true" reloadChanges="false" path="protocols.xml"/>
 226
 227 </SPConfig>
 228 ....
 229
 230 ==== Configuration to support multiple Evergreen hostnames
 231
 232 .Configuration for multiple hostnames
 233 [source:xml]
 234 ....
 235 <!-- Differences from the simple, single-host example are noted -->
 236 <SPConfig xmlns="urn:mace:shibboleth:2.0:native:sp:config"
 237     xmlns:conf="urn:mace:shibboleth:2.0:native:sp:config"
 238     xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
 239     xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
 240     xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
 241     clockSkew="180">
 242
 243 <!-- RequestMapper block differs from single-host example -->
 244    <RequestMapper type="Native">
 245         <RequestMap>
 246             <Host name="<your.evergreen.idp.domain>" applicationId="idp"/>
 247             <Host name="<your.evergreen.domain>" applicationId="otheridp"/>
 248         </RequestMap>
 249     </RequestMapper>
 250
 251     <!-- The ApplicationDefaults element is where most of Shibboleth's SAML bits are defined. This differs from single-host example. -->
 252     <ApplicationDefaults entityID="https://<your.evergreen.domain>/"
 253                          REMOTE_USER="eppn persistent-id targeted-id"
 254                          cipherSuites="ECDHE+AESGCM:ECDHE:!aNULL:!eNULL:!LOW:!EXPORT:!RC4:!SHA:!SSLv2">
 255
 256         <!--
 257         Controls session lifetimes, address checks, cookie handling, and the protocol handlers.
 258         You MUST supply an effectively unique handlerURL value for each of your applications.
 259         The value defaults to /Shibboleth.sso, and should be a relative path, with the SP computing
 260         a relative value based on the virtual host. Using handlerSSL="true", the default, will force
 261         the protocol to be https. You should also set cookieProps to "https" for SSL-only sites.
 262         Note that while we default checkAddress to "false", this has a negative impact on the
 263         security of your site. Stealing sessions via cookie theft is much easier with this disabled.
 264         -->
 265         <Sessions lifetime="28800" timeout="3600" relayState="ss:mem"
 266                   checkAddress="false" handlerSSL="true" cookieProps="https">
 267
 268
 269             <!--
 270             By not supplying an entity here, Evergreen is required to specify the entity.
 271             This is controlled by the opac.login.shib_sso.entityId YAOUS.
 272             -->
 273             <SSO>
 274               SAML2 SAML1
 275             </SSO>
 276
 277             <!-- SAML and local-only logout. -->
 278             <Logout>SAML2 Local</Logout>
 279
 280             <!-- Extension service that generates "approximate" metadata based on SP configuration. -->
 281             <Handler type="MetadataGenerator" Location="/Metadata" signing="false"/>
 282
 283             <!-- Status reporting service. -->
 284             <Handler type="Status" Location="/Status" acl="127.0.0.1 ::1"/>
 285
 286             <!-- Session diagnostic service. -->
 287             <Handler type="Session" Location="/Session" showAttributeValues="false"/>
 288
 289             <!-- JSON feed of discovery information. -->
 290             <Handler type="DiscoveryFeed" Location="/DiscoFeed"/>
 291
 292             <md:SingleLogoutService Location="/SLO/Redirect" conf:template="bindingTemplate.html"
 293                     conf:policyId="unsigned-slo" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"/>
 294
 295         </Sessions>
 296
 297         <!--
 298         Allows overriding of error template information/filenames. You can
 299         also add attributes with values that can be plugged into the templates.
 300         -->
 301         <Errors supportContact="root@localhost"
 302             helpLocation="/about.html"
 303             styleSheet="/shibboleth-sp/main.css"/>
 304
 305         <!-- Example of locally maintained metadata. -->
 306         <MetadataProvider type="XML" validate="true" file="/etc/shibboleth/simplesaml-idp-metadata.xml"/>
 307         <MetadataProvider type="XML" validate="true" file="/etc/shibboleth/other-external-idp-metadata.xml"/>
 308
 309         <!-- Map to extract attributes from SAML assertions. -->
 310         <AttributeExtractor type="XML" validate="true" reloadChanges="false" path="attribute-map.xml"/>
 311
 312         <!-- Use a SAML query if no attributes are supplied during SSO. -->
 313         <AttributeResolver type="Query" subjectMatch="true"/>
 314
 315         <!-- Default filtering policy for recognized attributes, lets other data pass. -->
 316         <AttributeFilter type="XML" validate="true" path="attribute-policy.xml"/>
 317
 318         <!-- Simple file-based resolver for using a single keypair. This differs from single-host example. -->
 319         <CredentialResolver type="File" key="sp-key.pem" certificate="sp-cert.pem"/>
 320
 321         <ApplicationOverride id="idp" entityID="https://<your.evergreen.idp.domain>/eg/opac/"/>
 322         <ApplicationOverride id="otheridp" entityID="https://<your.evergreen.domain>/eg/opac/"/>
 323
 324     </ApplicationDefaults>
 325
 326     <!-- Policies that determine how to process and authenticate runtime messages. -->
 327     <SecurityPolicyProvider type="XML" validate="true" path="security-policy.xml"/>
 328
 329     <!-- Low-level configuration about protocols and bindings available for use. -->
 330     <ProtocolProvider type="XML" validate="true" reloadChanges="false" path="protocols.xml"/>
 331
 332 </SPConfig>
 333 ....
 334
 335 ==== Other configuration information
 336
 337 Some common attribute maps that are useful for Microsoft ActiveDirectory
 338 and UNIX LDAP IdPs that can be added to attribute-map.xml are:
 339
 340 `+<Attribute name="urn:oid:1.2.840.113556.1.4.221" id="sAMAccountName"/>+`
 341
 342 `+<Attribute name="urn:oid:0.9.2342.19200300.100.1.1" id="uid"/>+`
 343
 344 `+<Attribute name="urn:oid:0.9.2342.19200300.100.1.3" id="mail"/>+`
 345
 346 `+<Attribute name="urn:mace:dir:attribute-def:uid" id="uid"/>+`
 347
 348 `+<Attribute name="urn:mace:dir:attribute-def:mail" id="mail"/>+`
 349
 350 For some IdPs, such as SimpleSAMLphp, it can be necessary to add a
 351 special security policy to security-policy.xml:
 352
 353 [source:xml]
 354 ....
 355 <Policy id="unsigned-slo">
 356     <PolicyRule type="NullSecurity"/>
 357 </Policy>
 358 ....
 359
 360 ==== Testing your configuration
 361
 362 To test if there is a current active Shibboleth session, go here:
 363 `+https://<your-eg-hostname>/Shibboleth.sso/Session+`
 364
 365 For testing purposes, if you need to reset the browser so it’s as if a
 366 user has never logged in before, this can be done by clearing all
 367 cookies associated with the Evergreen OPAC.