From Koha Wiki
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.
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
Shibboleth Daemon Configuration
Now that the packages are installed, you should find their configuration files under /etc/shibboleth.
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:
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:
<span class="kw2">sudo</span> service shibd restart <span class="kw2">sudo</span> 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:
Finally, you should be able to check the session status by navigating to:
Using AD FS Metadata
The metadata for an AD FS system is typically located at this address:
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.
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.
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
<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:
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:
<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!
Relevant bugs on Bugzilla
- Shibboleth authentication
- Fix OPACBaseURL to include protocol
- Shibboleth SingleSignOut *
- User logged out on refresh after Shibboleth authentication
- Shibboleth authentication for staff client
- Shibboleth auto-provisioning
- Shibboleth attribute manipulation *
- Shibboleth attributes may contain lists *
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.