Shibboleth is an open-source SAML implementation that is used for single sign-on. We are developing a SAML IdP, and I was testing it against Shibboleth. Here are some pieces of information that I want to keep for my records. I used Shibboleth with IIS 8.

Installation

I downloaded the latest package from the the download page. At the time of writing it was shibboleth-sp-2.5.6.0-win64.msi. The installer targets IIS 6, so I had to perform manual steps outlined in the IIS 7 Installer page.

The scripts on that page more or less work, but watch out for that extra new line before “/+[path”: you will need to remove it for the script to work. If you don’t, you will get this error

Handler "Shibboleth" has a bad module "ManagedPipelineHandler" in its module list

If this happens, make sure to repeat the manual steps for mapping .sso extension to Shibboleth filter.

After the installation is done, Shibboleth will protect the content of the http://yourhost/secure virtual directory.

Configuration

My Shibboleth configuration file. Note: this is not the actual file we use, some company specific information was removed.

Shibboleth configuration is stored in the shibboleth2.xml file. Standard configuration process involves going through the file and replacing default values such as host names with our specific data. However, default configuration uses SAML discovery protocol, which we do not support, so I had to perform more significant modifications:

1. Copy IdP’s SAML metadata to Shibboleth configuration directory (C:\opt\shibboleth-sp\etc\shibboleth).
    
2. Add the following node under <ApplicationDefaults>:
   <MetadataProvider type="XML" file="YourIdpMetadata.xml"/>
    
3. Remove <SSO> and <Logout> nodes under ApplicationDefaults/Sessions.
    
4. Add <SessionInitiator> node in their place:
   <SessionInitiator type="SAML2" Location="/Login" isDefault="true" id="Intranet"
relayState="cookie" entityID="https://your.idp/EntityId">
</SessionInitiator>
   I am not certain what is the role of the “location” attribute. It appears to be ignored: SAML requests are sent to the URL in the metadata.
    
5. If you leave it at that, Shibboleth will come up with a very cryptic message when you try to access http://yourhost/secure:
   Unable to locate a SAML 2.0 ACS endpoint to use for response.
   “ACS” here stands for “Assertion Consumer Service”. To get rid of the error, add the following node under <SessionInitiator>:

   <md:AssertionConsumerService Location="/SAML2/POST" index="1"
   Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" conf:ignoreNoPassive="true" />

   The documentation claims that an example is distributed with default shibboleth2.xml, but it is no longer the case. However, some examples can be found in the example-shibboleth2.xml file.

Restarting Shibboleth

Some configuration changes are picked up automatically, but for others you would have to restart Shibboleth. Run the following script as administrator

net stop shibd_default
iisreset
net start shibd_default

Log level

Log levels are set in configuration file shibd.logger. This is a standard log4j configuration file, change “INFO” in the second line to “DEBUG” to get more detailed output. Don’t forget to restart Shibboleth after that.

What’s Next

I will discuss how to integrate Shibboleth SP with your IdP to control access to various resources.