Shibboleth Configuration

From Koha Wiki

Jump to: navigation, search
Home > Documentation > Authentication > 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
sudo a2enmod shib2
sudo service apache2 restart

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, then 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
      AuthType shibboleth
      ShibRequireSession Off
      #Require valid-user
      Require shibboleth

Note: Please see the 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.

Swapping of metadata

Shibboleth requires the two parties 'Identity Provider' and 'Service Provider' to swap matadata. This is effectively the handshake that 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.

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:

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

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

Diagnosing problems

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

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

  <!-- Status reporting service. --> 
  <Handler type="Status" Location="/Status" acl="YOURIP" />

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

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:


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:

    <matchpoint>userid</matchpoint> <!-- koha borrowers field to match against for authentication -->
      <userid is="uid"></userid> <!-- mapping between koha borrowers field and shibboleth attribute name -->

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

Relevant bugs on Bugzilla

The once with * are not yet closed.


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!

Personal tools