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 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.
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 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.
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:
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:
<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 --> </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.