Here at the UW we use Shibboleth as a single federated login solution. There are fall backs and legacy options available, so before recently the Information School was using LDAP for login. The major advantage (and main reason central UW wants everyone to use Shibboleth) is that the login credentials are supplied only to the central UW IdP (Identity Provider). This makes login safer and more secure for the user.
So what is Shibboleth?
I asked the same question when I first heard about it. It’s a weird name and I’ve never heard of it before. Shibboleth is a product of the Internet2 consortium. In theory, Shibboleth should catch on all across higher ed and maybe the whole internet. Now that we’re using Shibboleth, the iSchool could allow folks with other InCommon federation member accounts to login with their native credentials on our site. We don’t currently have a need to do that, but in the future, who knows?
So how did I get it to work?
It’s really not as straight forward as I was hoping. The documentation in the IT wiki seems to be a bit out dated, or maybe just different than an Ubuntu package setup, so it wasn’t easy. First, and foremost, what we are doing is setting up a Shibboleth SP (Service Provider); we are not setting up an IdP (Identity Provider). The IdP is hosted centrally by UW and already running. What we need is a Shibboleth SP, with which we will connect to the IdP (and the InCommon federation, if you choose to).
The documentation on the Shibboleth site supports RedHat, SUSE, and OpenSUSE installations well. These are the officially supported Linux Distros. Of course, we’re using Ubuntu, so it seemed I would have to compile from source. This didn’t make me happy and I didn’t want to have to do that. So I went Googling and found out that Ubuntu has some packages available through apt-get that will work.
From a conglomeration of sites I figured it all out, but there are a lot of steps to get this to work. To get started we first have to install the Shibboleth SP which will run as a daemon (service) on the same web-server that will need to authenticate. At the iSchool we’re running Apache so we’ll also need a shibboleth module. The apt-get package will also require some dependency packages, but that’s all handled for us by apt-get.
To perform this setup you will need sudo or root access to the server that you’re installing Shibboleth on, and you’ll need to know your way around Linux a bit.
I’m assuming you have Apache installed and working, as well as SSL working on Apache.
First off, we need to grab some new packages, many of these have dependencies which apt-get will also be installing. Go ahead and update apt-get:
sudo apt-get update
Now start off by grabbing the shibboleth packages:
sudo apt-get install libapacahe2-mod-shib2 shibboleth-sp2-schemas
If you didn’t get any errors, you should have a /etc/shibboleth directory now. You should also have mod_shib_22.so in /usr/lib/apache2/modules, and you should have an Apache module load file in /etc/apache2/mods-available called shib2.load.
Now you’ll need to enable the Apache module:
sudo a2enmod shib2
Then restart Apache (this may be a different command for you):
sudo service apache2 restart
At this point, you can go ahead and start the Shibboleth daemon and see if things are somewhat working.
sudo service shibd start
You should see a message saying “Starting Shibboleth 2 daemon: shibd”. To test it out point your browser at your.domain.uw.edu/Shibboleth.sso/DS. This should redirect you to the placeholder URL https://ds.example.org… If it did, congrats, you have a working Shibboleth daemon. Now you have to configure it to work properly.
Configuring Shibboleth at the UW
This is where I had a heck of a time figuring out what to do. The install documentation in the UW wiki didn’t have much info about the config file, but after digging deeper I realized that there are separate articles beneath the Shibboleth Service Provider Support article (use the left nav to get to them).
The file you need to edit is /etc/shibboleth/shibboleth2.xml. This file will be full of example configuration SAML. You can either download this file from your server and open it on your desktop, or you can edit it in place with your favorite editor. Do note that the file is owned by root, so sudo when you open this file before you make all these changes if you’re using a command line editor (it sucks to forget to do that).
There are a few changes you’ll have to make in this giant file.
- In the InProcess block change the name attribute of the Site element to be whatever the domain name for your shibboleth install will be. For us it was ischool.uw.edu. In the same element, I added scheme=“https” and port=“443” attributes, to specify SSL.
Here is what your InProcess block should look like now:
<ISAPI normalizeRequest="true" safeHeaderNames="true">
<Site id="1" name="your.domain.uw.edu" scheme="https" port="443" />
- In the RequestMapper block, change the name attribute on Host to your.domain.uw.edu too.
- Now in the ApplicationDefaults block, change EntityID to https://your.domain.uw.edu.
This is what it should look like:
<ApplicationDefaults id="default" policyId="default"
REMOTE_USER="eppn persistent-id targeted-id"
- Further on, there’s a EntityID attribute on Session Initiator which needs to be changed to urn:mace:incommon:washington.edu and an ID attribute which needs to be changed to UW.
This is what that block should look like:
<SessionInitiator type="Chaining" Location="/DS" isDefault="true" id="UW"
relayState="cookie" entityID="urn:mace:incommon:washington.edu" forceAuthn="true">
<SessionInitiator type="SAML2" acsIndex="1" template="bindingTemplate.html"/>
<SessionInitiator type="Shib1" acsIndex="5"/>
In the above block, the forceAuthn=“true” toggle forces the user to re-enter their password on login even if they have a valid webauth session. We opted for this option since many of our users have web editing privileges on our site and the added security just made sense to us. If you don’t have a need for the extra security, you can go ahead nad change forceAuthn=“true” to forceAuthn=“false”.
- Now you need to remove or comment out the following two SessionInitiator blocks. The only active SessionInitiator block should be the one above.
- Further down, you’ll find a MetadataProvider block. Uncomment this block and make the changes as seen below:
<MetadataFilter type="RequireValidUntil" maxValidityInterval="2419200"/>
<MetadataFilter type="Signature" certificate="incommon.pem"/>
- Configuring logout requires a couple more changes. This time in /etc/shibboleth/localLogout.html add the following meta redirect below the content-type meta tag:
<meta http-equiv="Refresh" content="0;URL=https://idp.u.washington.edu/idp/logout"/>
And that was the last required change. There are also error configurations that can be set, but for more info on that you can check out the Shibboleth Wiki.
Save and upload your shibboleth2.xml file.
Next you’ll need to edit the /etc/shibboleth/attribute-map.xml. For info on what to edit here, see the UW documentation on this page.
You’re almost done! Now, if you want to you can revisit the test url I gave above: your.domain.uw.edu/Shibboleth.sso/DS and you should be seeing a new error. Something along the lines of opensaml::saml2md::MetadataException, Unable to locate metadata for identity provider (urn:mace:incommon:washington.edu). If you see that, it means your configuration file is (at least mostly) working as it should. Now you just need to complete a few more steps.
The reason it’s unable to find the Identity Provider metadata is due to a lack of the InCommon federation cert. The cert is linked to in the UW documentation and can be found at https://wayf.incommonfederation.org/bridge/certs/incommon.pem.To get it on your server, you can just run this command:
sudo wget -O /etc/shibboleth/incommon.pem https://wayf.incommonfederation.org/bridge/certs/incommon.pem
Alternatively you could just open the /etc/shibboleth/incommon.pem file for writing and paste the cert in, or FTP it up.
You also need to create a self signed cert for Shibboleth to use. The result will be a key file and a cert file. If you need help follow steps 1–4 in this tutorial. You’ll want to name these files sp-key.pem and sp-cert.pem, and copy or move them into /etc/shibboleth/.
Now you need to restart the Shibboleth daemon:
sudo service shibd restart
Hit the test url again and it should be forwarding you to idp.u.washington.edu/idp/profile/SAML2/Redirect/SSO. Your new error should be “Error Message: SAML 2 SSO profile is not configured for relying party ‘https://your.domain.uw.edu/shibboleth”. That means Shibboleth is configured to send your users over to the UW IdP. We’re almost done.
Registering with the IdP
Now you need to register your SP with UW and optionally register your SP with InCommon. The UW documentation is great here. We chose to only register with UW for now, so I’m not sure what the process is like with InCommon, but with UW it was pretty painless. One thing to note; You’ll need official domain access rights to register with UW.
After registering it takes a little while and after that the test URL should resolve to a working UW webauth login form. The next steps in this post are just about getting Shibboleth Auth set up in Drupal.
The Drupal Module
Now that we have Shibboleth up and working, we need to install the Shibboleth module for Drupal. This module works in both Drupal 6 and 7. We are currently using Drupal 6 for our production site, but we have a test server up with Drupal 7 on it. Both are using Shibboleth for auth.
This step is important and easy to miss. Add a few lines to your .htaccess file:
Now to configuring your new module. Navigate over to the shib_auth module configuration screen at /admin/user/shib_auth. You’ll need to change these Attribute settings (you can verify the accuracy of these variables by printing out $_SERVER after you are logged in via Shibboleth):
Server variable for username: HTTP_UWNETID
Server variable for e-mail address: HTTP_EPPN
Over on the advanced tab I also added in a URL to redirect to after logout. After that, all that’s left is adding the Shibboleth login block to your site. This will vary by site, so I’m not going to go over that beyond mentioning that the shibboleth module includes a login block that you can place on your site. How you want to get that there is up to you and your theme.
The goal of this post is to raise awareness of Shibboleth, and to assure everyone that it is possible to get it working with Drupal on Apache in Ubuntu. It’s also for our own step by step record of how to reproduce this in the future.