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).

It is recommended to limit the Shibboleth authentication module in Apache to the authentication page where it's actually used. Otherwise Apache will connect to the shibd daemon with each request, which consumes CPU and slows down each request. This is most prominent with high-traffic sites. The following example does this with Apache 2.4:

    <If "%{QUERY_STRING} =~ /auth_method=Shibboleth/">
      Require all denied
      AuthType shibboleth
      Require shibboleth
    </If>
    <Else>
      Require all granted
    </Else>

Note that you cannot use the above configuration if you need the checkExpiredSession setting for any reason.

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.

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 regardless of whether the user logged out from VuFind®, unless the browser is closed too.

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:

• https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPSingleLogoutService
• https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPNotify
• https://wiki.shibboleth.net/confluence/display/SHIB2/SLOWebappAdaptation

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"/>
            </LogoutInitiator>
 
            <!-- md:SingleLogoutService locations handle single logout (SLO) protocol messages. -->
            <md:SingleLogoutService Location="/SLO/SOAP"
                Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP"/>
            <md:SingleLogoutService Location="/SLO/Redirect" conf:template="bindingTemplate.html"
                Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"/>
            <md:SingleLogoutService Location="/SLO/POST" conf:template="bindingTemplate.html"
                Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"/>
            <md:SingleLogoutService Location="/SLO/Artifact" conf:template="bindingTemplate.html"
                Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact"/>
        </Sessions>
        <Notify Channel="back" Location="https://localhost/vufind/soap/shiblogout"/>
    </ApplicationDefaults>

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

[api.ShibbolethLogoutNotification]
permission = access.api.ShibbolethLogoutNotification
require = ANY
; IPv4
ipRange[] = '127.0.0.1'
; 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.

Ensure also that a mapping for session_id exists in config.ini:

[Shibboleth]
session_id = Shib-Session-ID

Set up periodic cleanup of the external_session table with the util/expire_external_sessions utility.

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"/>
  </SPSSODescriptor>
</EntityDescriptor>

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>' \
   'https://localhost/soap/shiblogout'

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