About Features Downloads Getting Started Documentation Events Support GitHub

Love VuFind®? Consider becoming a financial supporter. Your support helps build a better VuFind®!

Site Tools

Warning: This page has not been updated in over over a year and may be outdated or deprecated.

Shibboleth Configuration

Page Owneremaijala

Shibboleth Setup

You will first need to set up the Shibboleth Service Provider and its Apache module before setting it up in VuFind. You will also need to enable Shibboleth authentication in the Apache configuration (httpd-vufind.conf). Note that for high-traffic sites the Apache-Shibboleth daemon connection may use a relatively high amount of CPU, so you may want to limit the Shibboleth authentication to the authentication page where it's really needed with a configuration block like this (this example works with Apache 2.4):

    <If "%{QUERY_STRING} =~ /auth_method=Shibboleth/">
      Require all denied
      AuthType shibboleth
      Require shibboleth
      ShibRequestSetting requireSession false
      AuthType shibboleth
      Require shibboleth

Note: the “Else” clause can simply be “require all granted” if you are not using the Shibboleth “logout” setting… but if you are using “logout,” you need access to Shibboleth attributes at all times, and thus must always require the Shibboleth module.

The settings on VuFind side are found in the Shibboleth section in config.ini. Starting with VuFind 4.0 debug level log includes Shibboleth authentication handler messages to aid in debugging any issues with the authentication. These messages include the environment variables so that you can check if the environment variables that the Shibboleth module sets up matc the variable names in config.ini.

Shibboleth Single Logout

Support for Shibboleth back-channel single logout is available starting from VuFind version 4.0. Single logout is especially important in public terminals where the Shibboleth Identity Provider would keep the user's session alive unless the browser is closed too regardless of whether the user logged out from VuFind.

N.B. VuFind's Shibboleth logout notification handling requires the PHP SOAP module installed.

Here are some links for background information on how single logout works with Shibboleth:

VuFind supports the Shibboleth logout notification SOAP service that the Shibboleth Service Provider can be configured to call on logout. The service endpoint in VuFind is soap/shiblogout, i.e. http://vufind-server/vufind/soap/shiblogout with the default configuration. Here is an example configuration snippet for the Shibboleth SP (shibboleth2.xml) enabling the single logout handler and logout notification for VuFind (this is not a complete example but includes only the bits relevant to single logout):

    <ApplicationDefaults entityID="https://vufind-server"
                         REMOTE_USER="eppn persistent-id targeted-id" signing="front">
        <Sessions lifetime="28800" timeout="3600" checkAddress="false" relayState="ss:mem" handlerSSL="true" cookieProps="; path=/; secure; httpOnly">
            <!-- SAML and local-only logout. -->
            <Logout>SAML2 Local</Logout>
            <!-- LogoutInitiators enable SP-initiated local or global/single logout of sessions. -->
            <LogoutInitiator type="Chaining" Location="/Logout">
                <LogoutInitiator type="SAML2" template="bindingTemplate.html"/>
                <LogoutInitiator type="Local"/>
            <!-- md:SingleLogoutService locations handle single logout (SLO) protocol messages. -->
            <md:SingleLogoutService Location="/SLO/SOAP"
            <md:SingleLogoutService Location="/SLO/Redirect" conf:template="bindingTemplate.html"
            <md:SingleLogoutService Location="/SLO/POST" conf:template="bindingTemplate.html"
            <md:SingleLogoutService Location="/SLO/Artifact" conf:template="bindingTemplate.html"
        <Notify Channel="back" Location="https://localhost/vufind/soap/shiblogout"/>

You will also need to enable access to the SOAP endpoint from localhost in VuFind's permissions.ini:

permission = access.api.ShibbolethLogoutNotification
require = ANY
; IPv4
ipRange[] = ''
; IPv6
ipRange[] = '::1'

If you need to access the endpoint using a non-loopback IP address, add also the default IP address of the Shibboleth SP to the ipRange[] settings.

Finally, support for single logout in the service provider must be published in the federation metadata like this:

<EntityDescriptor ...>
  <SPSSODescriptor ...>
    <SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://vufind-server/Shibboleth.sso/SLO/Redirect"/>

Testing the Logout Handler

A logout request can be simulated to verify that the logout handler works:

  1. Start a session in VuFind.
  2. Do a search and check that it shows up in the search history.
  3. Take note of the session id by e.g. checking cookies with browser's developer tools.
  4. Add a mapping from an external ID (“Shibboleth session ID”) to the external session database table with the mysql cli client (replace SESSION_ID with the ID from step 3):
    INSERT INTO external_session (session_id, external_session_id) VALUES ('SESSION_ID', 'EXTERNAL_SESSION_ID');
  5. Use the following command to issue a logout request (replace `https://localhost` with your VuFind's address if necessary):
    curl -X POST --header "Content-Type: text/xml;charset=UTF-8" \
    --data \
    '<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"> \
      <s:Body> \
        <LogoutNotification xmlns="urn:mace:shibboleth:2.0:sp:notify" type="global"> \
          <SessionID>EXTERNAL_SESSION_ID</SessionID> \
        </LogoutNotification> \
      </s:Body> \
    </s:Envelope>' \

Advanced Options

See the Shibboleth and Library Cards page for details on setting up Shibboleth with VuFind's optional “Library Cards” feature.

configuration/shibboleth.txt · Last modified: 2022/10/28 11:09 by demiankatz