~evergreen-bugs/evergreen/rel_3_8

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
= 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 schools
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://<your.evergreen.domain>/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:

....
<VirtualHost *:443>
  ...
    SetEnv sso_loc 101
  # The following may be necessary based on how Shibboleth is configured
  <Location />
    ShibRequestSetting applicationId otheridp
  </Location>
  ...
</VirtualHost>
....

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.

==== eg_vhost.conf

Shibboleth needs be enabled in *eg_vhost.conf*. Uncomment the two lines in eg_vhost.conf as follows:

.eg_vhost.conf
[source,xml]
....
<Location /eg/opac>
    # Uncomment the entries below to enable Shibboleth authentication
    AuthType shibboleth
    Require shibboleth
....

=== 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]
....
<SPConfig xmlns="urn:mace:shibboleth:2.0:native:sp:config"
    xmlns:conf="urn:mace:shibboleth:2.0:native:sp:config"
    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
    xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
    xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
    clockSkew="180">

    <!-- The ApplicationDefaults element is where most of Shibboleth's SAML bits are defined. -->
    <ApplicationDefaults entityID="https://<your.evergreen.domain>/eg/opac/"
                         REMOTE_USER="eppn persistent-id targeted-id"
                         cipherSuites="ECDHE+AESGCM:ECDHE:!aNULL:!eNULL:!LOW:!EXPORT:!RC4:!SHA:!SSLv2">

        <!--
        Controls session lifetimes, address checks, cookie handling, and the protocol handlers.
        You MUST supply an effectively unique handlerURL value for each of your applications.
        The value defaults to /Shibboleth.sso, and should be a relative path, with the SP computing
        a relative value based on the virtual host. Using handlerSSL="true", the default, will force
        the protocol to be https. You should also set cookieProps to "https" for SSL-only sites.
        Note that while we default checkAddress to "false", this has a negative impact on the
        security of your site. Stealing sessions via cookie theft is much easier with this disabled.
        -->
        <Sessions lifetime="28800" timeout="3600" relayState="ss:mem"
                  checkAddress="false" handlerSSL="true" cookieProps="https">


            <!--
            By not supplying an entity here, Evergreen is required to specify the entity.
            This is controlled by the opac.login.shib_sso.entityId YAOUS.
            -->
            <SSO>
              SAML2 SAML1
            </SSO>

            <!-- SAML and local-only logout. -->
            <Logout>SAML2 Local</Logout>

            <!-- Extension service that generates "approximate" metadata based on SP configuration. -->
            <Handler type="MetadataGenerator" Location="/Metadata" signing="false"/>

            <!-- Status reporting service. -->
            <Handler type="Status" Location="/Status" acl="127.0.0.1 ::1"/>

            <!-- Session diagnostic service. -->
            <Handler type="Session" Location="/Session" showAttributeValues="false"/>

            <!-- JSON feed of discovery information. -->
            <Handler type="DiscoveryFeed" Location="/DiscoFeed"/>

            <md:SingleLogoutService Location="/SLO/Redirect" conf:template="bindingTemplate.html"
                    conf:policyId="unsigned-slo" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"/>

        </Sessions>

        <!--
        Allows overriding of error template information/filenames. You can
        also add attributes with values that can be plugged into the templates.
        -->
        <Errors supportContact="root@localhost"
            helpLocation="/about.html"
            styleSheet="/shibboleth-sp/main.css"/>

        <!-- Example of locally maintained metadata. -->
        <MetadataProvider type="XML" validate="true" file="/etc/shibboleth/simplesaml-idp-metadata.xml"/>
        <MetadataProvider type="XML" validate="true" file="/etc/shibboleth/other-external-idp-metadata.xml"/>

        <!-- Map to extract attributes from SAML assertions. -->
        <AttributeExtractor type="XML" validate="true" reloadChanges="false" path="attribute-map.xml"/>

        <!-- Use a SAML query if no attributes are supplied during SSO. -->
        <AttributeResolver type="Query" subjectMatch="true"/>

        <!-- Default filtering policy for recognized attributes, lets other data pass. -->
        <AttributeFilter type="XML" validate="true" path="attribute-policy.xml"/>

        <!-- Simple file-based resolver for using a single keypair. -->
        <CredentialResolver type="File" key="sp-key.pem" certificate="sp-cert.pem"/>

    </ApplicationDefaults>

    <!-- Policies that determine how to process and authenticate runtime messages. -->
    <SecurityPolicyProvider type="XML" validate="true" path="security-policy.xml"/>

    <!-- Low-level configuration about protocols and bindings available for use. -->
    <ProtocolProvider type="XML" validate="true" reloadChanges="false" path="protocols.xml"/>

</SPConfig>
....

==== Configuration to support multiple Evergreen hostnames

.Configuration for multiple hostnames
[source,xml]
....
<!-- Differences from the simple, single-host example are noted -->
<SPConfig xmlns="urn:mace:shibboleth:2.0:native:sp:config"
    xmlns:conf="urn:mace:shibboleth:2.0:native:sp:config"
    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
    xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
    xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
    clockSkew="180">

<!-- RequestMapper block differs from single-host example -->
   <RequestMapper type="Native">
        <RequestMap>
            <Host name="<your.evergreen.idp.domain>" applicationId="idp"/>
            <Host name="<your.evergreen.domain>" applicationId="otheridp"/>
        </RequestMap>
    </RequestMapper>

    <!-- The ApplicationDefaults element is where most of Shibboleth's SAML bits are defined. This differs from single-host example. -->
    <ApplicationDefaults entityID="https://<your.evergreen.domain>/"
                         REMOTE_USER="eppn persistent-id targeted-id"
                         cipherSuites="ECDHE+AESGCM:ECDHE:!aNULL:!eNULL:!LOW:!EXPORT:!RC4:!SHA:!SSLv2">

        <!--
        Controls session lifetimes, address checks, cookie handling, and the protocol handlers.
        You MUST supply an effectively unique handlerURL value for each of your applications.
        The value defaults to /Shibboleth.sso, and should be a relative path, with the SP computing
        a relative value based on the virtual host. Using handlerSSL="true", the default, will force
        the protocol to be https. You should also set cookieProps to "https" for SSL-only sites.
        Note that while we default checkAddress to "false", this has a negative impact on the
        security of your site. Stealing sessions via cookie theft is much easier with this disabled.
        -->
        <Sessions lifetime="28800" timeout="3600" relayState="ss:mem"
                  checkAddress="false" handlerSSL="true" cookieProps="https">


            <!--
            By not supplying an entity here, Evergreen is required to specify the entity.
            This is controlled by the opac.login.shib_sso.entityId YAOUS.
            -->
            <SSO>
              SAML2 SAML1
            </SSO>

            <!-- SAML and local-only logout. -->
            <Logout>SAML2 Local</Logout>

            <!-- Extension service that generates "approximate" metadata based on SP configuration. -->
            <Handler type="MetadataGenerator" Location="/Metadata" signing="false"/>

            <!-- Status reporting service. -->
            <Handler type="Status" Location="/Status" acl="127.0.0.1 ::1"/>

            <!-- Session diagnostic service. -->
            <Handler type="Session" Location="/Session" showAttributeValues="false"/>

            <!-- JSON feed of discovery information. -->
            <Handler type="DiscoveryFeed" Location="/DiscoFeed"/>

            <md:SingleLogoutService Location="/SLO/Redirect" conf:template="bindingTemplate.html"
                    conf:policyId="unsigned-slo" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"/>

        </Sessions>

        <!--
        Allows overriding of error template information/filenames. You can
        also add attributes with values that can be plugged into the templates.
        -->
        <Errors supportContact="root@localhost"
            helpLocation="/about.html"
            styleSheet="/shibboleth-sp/main.css"/>

        <!-- Example of locally maintained metadata. -->
        <MetadataProvider type="XML" validate="true" file="/etc/shibboleth/simplesaml-idp-metadata.xml"/>
        <MetadataProvider type="XML" validate="true" file="/etc/shibboleth/other-external-idp-metadata.xml"/>

        <!-- Map to extract attributes from SAML assertions. -->
        <AttributeExtractor type="XML" validate="true" reloadChanges="false" path="attribute-map.xml"/>

        <!-- Use a SAML query if no attributes are supplied during SSO. -->
        <AttributeResolver type="Query" subjectMatch="true"/>

        <!-- Default filtering policy for recognized attributes, lets other data pass. -->
        <AttributeFilter type="XML" validate="true" path="attribute-policy.xml"/>

        <!-- Simple file-based resolver for using a single keypair. This differs from single-host example. -->
        <CredentialResolver type="File" key="sp-key.pem" certificate="sp-cert.pem"/>

        <ApplicationOverride id="idp" entityID="https://<your.evergreen.idp.domain>/eg/opac/"/>
        <ApplicationOverride id="otheridp" entityID="https://<your.evergreen.domain>/eg/opac/"/>

    </ApplicationDefaults>

    <!-- Policies that determine how to process and authenticate runtime messages. -->
    <SecurityPolicyProvider type="XML" validate="true" path="security-policy.xml"/>

    <!-- Low-level configuration about protocols and bindings available for use. -->
    <ProtocolProvider type="XML" validate="true" reloadChanges="false" path="protocols.xml"/>

</SPConfig>
....

==== 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:

`+<Attribute name="urn:oid:1.2.840.113556.1.4.221" id="sAMAccountName"/>+`

`+<Attribute name="urn:oid:0.9.2342.19200300.100.1.1" id="uid"/>+`

`+<Attribute name="urn:oid:0.9.2342.19200300.100.1.3" id="mail"/>+`

`+<Attribute name="urn:mace:dir:attribute-def:uid" id="uid"/>+`

`+<Attribute name="urn:mace:dir:attribute-def:mail" id="mail"/>+`

For some IdPs, such as SimpleSAMLphp, it can be necessary to add a
special security policy to security-policy.xml:

[source,xml]
....
<Policy id="unsigned-slo">
    <PolicyRule type="NullSecurity"/>
</Policy>
....

==== Testing your configuration

To test if there is a current active Shibboleth session, go here:
`+https://<your-eg-hostname>/Shibboleth.sso/Session+`

For testing purposes, if you need to reset the browser so its as if a
user has never logged in before, this can be done by clearing all
cookies associated with the Evergreen OPAC.