Shibboleth

Shibboleth in Koha, as per normal practice, relies heavily upon the native shibboleth service provider packages in your given distribution. Installing and configuring these is the majority of the work required to get shibboleth authentication up and running, and so I have outlined the basic procedure below.

This guide assumes you are using the latest Debian stable release, though it should be easily adaptable to other distrobutions.

Installing dependencies

Shibboleth requires a few dependancies to be installed. Thankfully, they are all in the default repositories for debian.

sudo apt-get install shibboleth-sp2-schemas libapache2-mod-shib2 # Debian before Stretch
# or
sudo apt-get install shibboleth-sp2-common libapache2-mod-shib2 # Debian Stretch and later

sudo a2enmod shib2
sudo service apache2 restart

On newer systems this seems to be shibboleth-sp2-common

Known issues

Due to dependency issues involving libxmltoolking7 and libcurl3/libcurl4 on Ubuntu 18.04, installation of libapache2-mod-shib2 appears to be impossible using Ubuntu repositories on that OS version.

Shibboleth bugs in Ubuntu 18.04

Shibboleth Daemon Configuration

Now that the packages are installed, you should find their configuration files under /etc/shibboleth.

Adding Keys

For shibboleth to function, we must create a unique key pair for the daemon.

cd /etc/shibboleth
sudo shib-keygen -f

Once created, you must correct the default details in /etc/shibboleth/shibboleth2.xml to point to your new certificate and key pair.

Service Provider Configuration

All shibboleth configuration goes on inside /etc/shibboleth/shibboleth2.xml

I have provided an annotated example configuration to get you started.

Adding Directories and Permissions

If you are using the above template configuration (and you're not using AD FS), you will need to create some additional directories for shibboleth to run correctly.

sudo mkdir /var/cache/shibboleth
sudo mkdir /var/cache/shibboleth/metadata
sudo chown -R _shibd:_shibd /var/cache/shibboleth
sudo service shibd restart

Enabling Shibboleth for your Virtualhost

A default configuration for your virtualhost for shibboleth is included with koha; but it is commented out.

You will need to uncomment and adapt the following lines

   # Optional Shibboleth Configuration
   <Location />
      ShibRequestSetting applicationId gitified.osils.de
      AuthType shibboleth
      ShibRequireSession Off
      #Require valid-user
      Require shibboleth
   </Location>

Note: Please see the Auth_with_shib.pm POD for details of an alternate configuration for use in Plack environments. Note: If you wish to also use Shibboleth for the staff client you may wish to copy this block into the staff client virtualhost and adapt it to match the entityId's of the corresponding ApplicationOverride section in your Shibboleth2.xml configuration.

This section was missing from a more recent Koha installation, so you may need to retype or paste inside the VirtualHost section. If you are using AD FS, you may also need to comment out the ShibRequestSetting line.

Important: Before moving on from this section, you should be able to visit this address and see an xml file download, with no errors shown in your browser:

https://kohaserver.yourdomain.example.com/Shibboleth.sso/Metadata

Swapping of metadata

Shibboleth requires the two parties 'Identity Provider' (IdP) and 'Service Provider' (SP) to swap metadata. This is the handshake which allows the two parties to establish a 'trust relationship'.

For a basic setup, the dynamically created metadata provided by the native service provider software is probably good enough to get you started. Look in /etc/shibboleth/filtered-metadata.xml

Restart your apache and shibd process to make sure all your changes have taken effect:

sudo service shibd restart
sudo service apache2 restart

Your example metadata should now be available at:

https://kohaserver.yourdomain.example.com/Shibboleth.sso/Metadata If you are using AD FS, you can use also this address to create the Relying Party Trust.

Once you've swapped metadata, you should be able to get a shibboleth session to work with by navigating to:

https://kohaserver.yourdomain.example.com/Shibboleth.sso/Login

Finally, you should be able to check the session status by navigating to:

https://kohaserver.yourdomain.example.com/Shibboleth.sso/Session

Using AD FS Metadata

The metadata for an AD FS system is typically located at this address:

https://adfsserver.yourdomain.example.com/FederationMetadata/2007-06/FederationMetadata.xml

However, the metadata provided here is not fully compatible with Shibboleth. To make use of this metadata, download the file and open it in a good text editor. Then follow this information on adding the required scope element. Pay special attention to step six at the link to use your own scope rather than contoso.com. When you finish changing the file, upload it to your koha server, and move it to /etc/shibboleth/filtered-metadata.xml. Don't forget to check ownership and permissions after moving the file.

Claims Rules

Your IdP will need to issue some claims rules in the Service Provider/Relying Party configuration.

For AD FS, follow this guide very carefully to create the claims rules.
The rules for the groups are optional, but you should still end up with two rules: 1 to extract the UPN (or sAmAccountName), and another to transform it for Shibboleth.

This is also a good time to check you have both sets of Endpoints and Identifiers (for both the OPAC and Intranet views) included with your AD FS Relying Party.

Diagnosing problems

You can enable some extra diagnostic information to be available at:

https://kohaserver.yourdomain.example.com/Shibboleth.sso/Status

By adding your personal IP into the below line in shibboleth2.xml and restarting the service

  <span class="sc-1"><!-- Status reporting service. --></span> <span class="sc3"><span class="re1"><Handler</span> <span class="re0">type</span>=<span class="st0">"Status"</span> <span class="re0">Location</span>=<span class="st0">"/Status"</span> <span class="re0">acl</span>=<span class="st0">"YOURIP"</span> <span class="re2">/></span></span>

Now you should be able to see any mapped attributes at:

https://kohaserver.yourdomain.example.com/Shibboleth.sso/Session

Mapping shibboleth attribute to server environment variables

If we're lucky, the attributes being sent to us will already be enabled by default. However this is often not the case, so we may need to add some mappings to the file:

/etc/shibboleth/attribute-map.xml

It may be helpful to turn up logging at this point so ascertain what attributes are being sent and are unmapped from the logs. The file to edit is /etc/shibboleth/shibd.logger, lets set to DEBUG:

# set overall behavior
log4j.rootCategory=DEBUG, shibd_log, warn_log

Now we can monitor the logs whilst we perform a login to see what attribute are not being mapped:

tail -f /var/log/shibboleth/shibd.log

The lines you're looking for will appear something like the below:

  skipping unmapped SAML 2.0 Attribute with Name: sn

Either uncomment those attributes, or add them if they don't exist, in /etc/shibboleth/attribute-map.xml and then restart the shibd daemon for changes to take effect.

Add shibboleth to koha-conf.xml

So, with any luck we now have a working shibboleth trust relationship, and can login to a shibboleth IdP and get a returned shibboleth session with mapped attributes!

That's the hardest bit over, new we need to configure Koha to take notice of that login and attributes.

The shibboleth configuration in koha is contained in the koha-conf.xml file. As a bare minimum you will need a block similar to the following:

  <useshibboleth>1</useshibboleth>
  <shibboleth>
    <matchpoint>userid</matchpoint> <!-- koha borrowers field to match against for authentication -->
    <mapping>
      <userid is="uid"></userid> <!-- mapping between koha borrowers field and shibboleth attribute name. AD FS should use eppn instead of uid. -->
    </mapping>
  </shibboleth>

That's it.. you should now be good to go!

User provisioning with Shibboleth

Inside the shibboleth block in the koha-conf.xml, add an autocreate element and set it to 1.

  <useshibboleth>1</useshibboleth>
  <shibboleth>
    <autocreate>1</autocreate>
    <matchpoint>userid</matchpoint> <!-- koha borrowers field to match against for authentication -->
    <mapping>
      <userid is="uid"></userid> <!-- mapping between koha borrowers field and shibboleth attribute name. AD FS should use eppn instead of uid. -->
    </mapping>
  </shibboleth>

You'll need to set in the mapping any attributes you want your auto-created users to have, just like userid has been mapped above. Categorycode and branchcode are mandatory.

If you want to set a default, for example for categorycode and branchcode, you can add a 'content' and as well as 'is' attribute to the element.

  <useshibboleth>1</useshibboleth>
  <shibboleth>
    <autocreate>1</autocreate>
    <matchpoint>userid</matchpoint> <!-- koha borrowers field to match against for authentication -->
    <mapping>
      <userid is="uid"></userid> <!-- mapping between koha borrowers field and shibboleth attribute name. AD FS should use eppn instead of uid. -->
      <branchcode content="MAIN" is="MAIN"></branchcode>
      <categorycode content="STAFF" is="STAFF"></categorycode>
    </mapping>
  </shibboleth>

Relevant bugs on Bugzilla

The once with * are not yet closed.

Disclaimer

Shibboleth is an insanely complex protocol, hence why we are using the native service provider software to do allot of the work for us.

I've tried to make the example configuration as simple and descriptive as possible, but I cannot account for the many variables than can crop up.

Good Luck!

Shibboleth Configuration

Contents