Shibboleth's Lil Helper (slh) is a tool that automates the generation of Apache/IIS Shibboleth Native Service Provider configuration & metadata files. It provides several benefits over manually configuring each NativeSp instance/server by:
Providing a consistent configuration approach applied uniformly across all servers in your organization via one easy-to-read config file describing shib config across X web servers (IIS and Apache), Y sites, and Z directory paths.
Providing conceptually simple linear process that distills the main steps associated with Shibboleth integration.
- initialize a config.rb file
- edit slh config.rb file
- generate shib2.xml (and deploy to web server hosts)
- verify sp metadata correctness
- generate metadata
- send metadata to idp
- verify all is well
Dividing high level auth specs from actual NativeSp configuration
- Programmers can focus on high level goals like "protect files underneath the '/secure' directory on 'somewebsite.com'" rather than grappeling with the bewildering complexity of the NativeSp's interrelated XML files, the Shibboleth protocal, SAML, etc.
- shibboleth-2.4.3 is installed on your target hosts. Versions greater than this should work too, but have not been tested.
- Each web server host integrates with a single Identity Provider, not multiple.
- All sites on a particular web server host use the same Service Provider Entity ID.
- (for Apache) The Shibboleth apache module is loaded globally for all vHosts. (This doesn't mean that it requires auth globally--just available, see lib/slh/templates/shib_apache.conf.erb for what this looks like).
Via Ruby Gems:
gem install shibboleths_lil_helper
- Then type
slh-- this provides more detailed/actionable documentation
Via Git: (for developers/contributors)
- this is how developers/contributors should install the tool
git clone ...git://thisrepo_or_a_fork... slh
- then add a symlink to bin/slh (something like below)
ln -s bin/slh ~/slh_local
- run commands on your test config.rb with
slh_local generate_metadata, etc
- Tool requires nokogiri gem which in-turn requires libxml2, you may run into difficulties there: See http://nokogiri.org/tutorials/installing_nokogiri.html if you have problems.
Before using this tool
For each host you want to integrate with Shibboleth, do the following and have answers for the questions below.
Don't try to use this tool until you have followed these instructions for at least one host.
For each host:
Install Shibboleth Native Service Provider Apache/IIS https://wiki.shibboleth.net/confluence/display/SHIB2/Installation Ideally, you should be able to hit a URL like "Shibboleth.ss/Metadata" for each site on the host and have it cough out some XML goo. (not a strict requirement, slh will help you with this later too)
What web server is it? IIS or Apache
If IIS, what is the site ID?
You can find this my clicking "Websites" in IIS and looking at the "Identifier" column for myshinynewwebsite.umn.edu.
What is the host name of the computer? (e.g. somehost.com)
What is the site name? (e.g. myshinynewwebsite.umn.edu)
Is authentication required for the entire site or particular directories?
Is this URL available for your site? myshinynewwebsite.umn.edu/Shibboleth.sso/Metadata
What is the error support contact email?
What is the Service Provider entity ID you'd like to use? A simple convention is to have a dev entity for "development" or "staging" apps and one for production stuff. You might consider https://YOUR_ORG.umn.edu/shibboleth/dev_default or https://YOUR_ORG.umn.edu/shibboleth/prod_default
All configuration and authentication specs for all Shibboleth SP instances are specified in a single ruby parseable
shibboleths_lil_helper/config.rb file. From these specs, slh is capable of generating all of the required XML files you will need to integrate with a Shibboleth Identify Provider (Idp). The following breaks down the essential steps.
1. Initialize a config.rb file
mkdir shibboleth_deployer cd shibboleth_deployer slh initialize
This creates a config file with example code you'll need to change to work.
The generated config.rb contains instructions and examples of valid configuration options to set your:
- idp_metadata_url : the URL (NOT the idp entity ID) for you IDP's metadata
- strategies, hosts, sites, and paths to protect
3. Generate shibboleth2.xml and deploy to web server hosts
In the directory one up from "shibboleths_lil_helper" (in this case shibboleth_deployer), type
This creates files for each web server host:
- idp_metadata.xml (this is simply a copy of the IDP metadata at :idp_metadata_url
- shib_apache.conf (if using apache)
shibboleth2.xml contains a and other goo needed to integrate with an Shib IDP to reflect the sites and paths your want protected.
You must deploy these files to each host and restart the shib daeman/service and apache/IIS.
You must also arbitrarily pick one particular site in each strategy to
set :is_key_originator,true for, if you see this more in a strategy, it will NOT WORK. (also, don't set it to false, just remove the line in all but one site)
set :is_key_originator, true tells slh that this site has the authoriative X509Certificate (in the SP metadata) that all other sites should match against (used in the verify_metadata command).
It implies that each host in your strategy has the same sp-key.pem and sp-cert.pem files as the host where the "is_key_originator" site lives.
It also implies that, when you setup a new web server host: copy the sp-key and sp-cert files from this "is_key_originator" host to the new host.
4. Verify SP metadata correctness
Once you've deployed you shibboleth2.xml, idp_metadata.xml, shib_apache, and sp-key, and sp-cert to all hosts, you can
Verify your metadata data across all hosts with:
This command will provide useful output and instructions to get your SP metadat setup correctly.
This command and generate_metadata rely on URLs like
being publically available. If this command is erroring out, its likely
due to the fact that one or more sites does not expose this URL (and
likely requires a change to shibboleth2.xml, i.e. tweak config.rb,
slh generate, and redeploy to server).
5. Generate SP metadata
If verify_metadata is not showing any errors, you can proceed to
which generates an SP metadata file for each SP entity id in in a file like:
This SP Metadata file MUST BE INSTALLED on the IDP to proceed!!! Typically this is done by emailing the file to your identity management team
6. Send SP metadata to IDP folks
Send the _sp_metadata_for_idp.xml to your IDP folks.
7. Verify all is well
Hit somesite.com/Shibboleth.sso/Login and be happily prompted for login.
Deployment automation (on Unix/Apache)
Once you have the basic stuff working, you may want to automate deployment:
will create a config/deploy.rb
See https://github.com/capistrano/capistrano/wiki/ for more details
This requires some initial setup per host and only works well if your target hosts run SSH (aka default not-IIS setup)
deployment automation example
Only works on Unix/Apache
We have a private repo called shibboleth_deployer that includes the shibboleths_lil_helper generated config files and uses Capistrano to push these files out target servers and restarts shibd and httpd. It's usage looks like:
cap deploy HOST=asr-web-dev4.oit.umn.edu
For each of our target servers we setup Capistrano to have a clone of this shibboleth_deployer repo structured in the standard way:
ls /etc/shibboleth_deployer current releases shared
Setup symlinks to the appropriate config files within shibboleth_deployer from the places the Native Shibboleth SP expects files to be, e.g:
from the /etc/shibboleth dir
ln -s /etc/shibboleth_deployer/current/shibboleths_lil_helper/generated/apache_shib_test_server/asr-web-dev4.oit.umn.edu/shibboleth2.xml shibboleth2.xml ln -s /etc/shibboleth_deployer/current/shibboleths_lil_helper/generated/apache_shib_test_server/asr-web-dev4.oit.umn.edu/idp_metadata.xml idp_metadata.xml
from the /etc/httpd/conf.d dir
ln -s /etc/shibboleth_deployer/current/shibboleths_lil_helper/generated/apache_shib_test_server/asr-web-dev4.oit.umn.edu/shib_apache.conf shib_apache.conf
This code is under active development.
gem update shibboleths_lil_helperto get the most current version.
- See CHANGLOG.markdown for the changes associated with each gem release.
How to help/contribute
To suggest enhancements or changes let us know via Github Issues (preferred) or email.
To share your experience, tricks, nuances, gotchas, and perspectives, please see and add to the Github Wiki.
To add features or fix stuff yourself: fork, implement, issue a pull request.
- Joe Goggins, Academic Support Resources, firstname.lastname@example.org
- Chris Dinger, Academic Support Resources, email@example.com
Thanks to these folks for providing feedback and willingness to pilot the tool.
- David Peterson, Office of Institutional Research
- Debbie Gillespie, Computer Science and Engineering
- Eva Young, Office of Institional Compliance
- Josh Buysse, CLA Office of Information Technology
- Aaron Zirbes, Environmental Health Sciences
- Rex Wheeler, University of Minnesota Extension
Copyright (c) Regents of the University of Minnesota