Here at the UW we use Shib­bo­leth as a sin­gle fed­er­ated login solu­tion. There are fall backs and legacy options avail­able, so before recently the Infor­ma­tion School was using LDAP for login. The major advan­tage (and main rea­son cen­tral UW wants every­one to use Shib­bo­leth) is that the login cre­den­tials are sup­plied only to the cen­tral UW IdP (Iden­tity Provider). This makes login safer and more secure for the user.

So what is Shibboleth?

I asked the same ques­tion when I first heard about it. It’s a weird name and I’ve never heard of it before. Shib­bo­leth is a prod­uct of the Internet2 con­sor­tium. In the­ory, Shib­bo­leth should catch on all across higher ed and maybe the whole inter­net. Now that we’re using Shib­bo­leth, the iSchool could allow folks with other InCom­mon fed­er­a­tion mem­ber accounts to login with their native cre­den­tials on our site. We don’t cur­rently 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 for­ward as I was hop­ing. The doc­u­men­ta­tion in the IT wiki seems to be a bit out dated, or maybe just dif­fer­ent than an Ubuntu pack­age setup, so it wasn’t easy. First, and fore­most, what we are doing is set­ting up a Shib­bo­leth SP (Ser­vice Provider); we are not set­ting up an IdP (Iden­tity Provider). The IdP is hosted cen­trally by UW and already run­ning. What we need is a Shib­bo­leth SP, with which we will con­nect to the IdP (and the InCom­mon fed­er­a­tion, if you choose to).

The doc­u­men­ta­tion on the Shib­bo­leth site sup­ports Red­Hat, SUSE, and Open­SUSE instal­la­tions well. These are the offi­cially sup­ported Linux Dis­tros. Of course, we’re using Ubuntu, so it seemed I would have to com­pile 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 pack­ages avail­able through apt-get that will work.

From a con­glom­er­a­tion of sites I fig­ured it all out, but there are a lot of steps to get this to work. To get started we first have to install the Shib­bo­leth SP which will run as a dae­mon (ser­vice) on the same web-server that will need to authen­ti­cate. At the iSchool we’re run­ning Apache so we’ll also need a shib­bo­leth mod­ule. The apt-get pack­age will also require some depen­dency pack­ages, but that’s all han­dled for us by apt-get.

To per­form this setup you will need sudo or root access to the server that you’re installing Shib­bo­leth on, and you’ll need to know your way around Linux a bit.

The install

I’m assum­ing you have Apache installed and work­ing, as well as SSL work­ing on Apache.

First off, we need to grab some new pack­ages, many of these have depen­den­cies which apt-get will also be installing. Go ahead and update apt-get:

sudo apt-get update

Now start off by grab­bing the shib­bo­leth packages:

sudo apt-get install libapacahe2-mod-shib2 shibboleth-sp2-schemas

If you didn’t get any errors, you should have a /etc/shibboleth direc­tory now. You should also have mod_shib_22.so in /usr/lib/apache2/modules, and you should have an Apache mod­ule 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 dif­fer­ent com­mand for you):

sudo service apache2 restart

At this point, you can go ahead and start the Shib­bo­leth dae­mon and see if things are some­what working.

sudo service shibd start

You should see a mes­sage say­ing “Start­ing Shib­bo­leth 2 dae­mon: shibd”. To test it out point your browser at your.domain.uw.edu/Shibboleth.sso/DS. This should redi­rect you to the place­holder URL https://ds.example.org… If it did, con­grats, you have a work­ing Shib­bo­leth dae­mon. Now you have to con­fig­ure it to work properly.

Con­fig­ur­ing Shib­bo­leth at the UW

This is where I had a heck of a time fig­ur­ing out what to do. The install doc­u­men­ta­tion in the UW wiki didn’t have much info about the con­fig file, but after dig­ging deeper I real­ized that there are sep­a­rate arti­cles beneath the Shib­bo­leth Ser­vice Provider Sup­port arti­cle (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 exam­ple con­fig­u­ra­tion SAML. You can either down­load this file from your server and open it on your desk­top, or you can edit it in place with your favorite edi­tor. 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 com­mand line edi­tor (it sucks to for­get to do that).

There are a few changes you’ll have to make in this giant file.

1. In the InProcess block change the name attribute of the Site ele­ment to be what­ever the domain name for your shib­bo­leth install will be. For us it was ischool.uw.edu. In the same ele­ment, I added scheme=“https” and port=“443” attrib­utes, to spec­ify SSL.

<InProcess logger="native.logger">
    <ISAPI normalizeRequest="true" safeHeaderNames="true">
        <Site id="1" name="your.domain.uw.edu" scheme="https" port="443" />
    </ISAPI>
</InProcess>

2. In the RequestMap­per block, change the name attribute on Host to your.domain.uw.edu too.

3. Now in the Appli­ca­tion­De­faults block, change Enti­tyID to https://your.domain.uw.edu.

    <ApplicationDefaults id="default" policyId="default"
        entityID="https://your.domain.uw.edu/shibboleth"
        REMOTE_USER="eppn persistent-id targeted-id"
        signing="false" encryption="false">

4. Fur­ther on, there’s a Enti­tyID attribute on Ses­sion Ini­tia­tor which needs to be changed to urn:mace:incommon:washington.edu and an ID attribute which needs to be changed to UW.

<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"/>
</SessionInitiator>

In the above block, the forceAuthn=“true” tog­gle forces the user to re-enter their pass­word on login even if they have a valid webauth ses­sion. We opted for this option since many of our users have web edit­ing priv­i­leges on our site and the added secu­rity just made sense to us. If you don’t have a need for the extra secu­rity, you can go ahead nad change forceAuthn=“true” to forceAuthn=“false”.

5. Now you need to remove or com­ment out the fol­low­ing two Ses­sion­Ini­tia­tor blocks. The only active Ses­sion­Ini­tia­tor block should be the one above.

6. Fur­ther down, you’ll find a Meta­dat­aProvider block. Uncom­ment this block and make the changes as seen below:

<MetadataProvider type="XML"
        uri="http://wayf.incommonfederation.org/InCommon/InCommon-metadata.xml"
	backingFilePath="InCommon-metadata.xml" reloadInterval="7200">
    <MetadataFilter type="RequireValidUntil" maxValidityInterval="2419200"/>
    <MetadataFilter type="Signature" certificate="incommon.pem"/>
</MetadataProvider>

7. Con­fig­ur­ing logout requires a cou­ple more changes. This time in /etc/shibboleth/localLogout.html add the fol­low­ing meta redi­rect 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 con­fig­u­ra­tions that can be set, but for more info on that you can check out the Shib­bo­leth 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 doc­u­men­ta­tion 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 see­ing a new error. Some­thing along the lines of opensaml::saml2md::MetadataException, Unable to locate meta­data for iden­tity provider (urn:mace:incommon:washington.edu). If you see that, it means your con­fig­u­ra­tion file is (at least mostly) work­ing as it should. Now you just need to com­plete a few more steps.

Secu­rity keys

The rea­son it’s unable to find the Iden­tity Provider meta­data is due to a lack of the InCom­mon fed­er­a­tion cert. The cert is linked to in the UW doc­u­men­ta­tion 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

Alter­na­tively you could just open the /etc/shibboleth/incommon.pem file for writ­ing and paste the cert in, or FTP it up.

You also need to cre­ate a self signed cert for Shib­bo­leth to use. The result will be a key file and a cert file. If you need help fol­low steps 1–4 in this tuto­r­ial. 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 Shib­bo­leth daemon:

sudo service shibd restart

Hit the test url again and it should be for­ward­ing you to idp.u.washington.edu/idp/profile/SAML2/Redirect/SSO. Your new error should be “Error Mes­sage: SAML 2 SSO pro­file is not con­fig­ured for rely­ing party ‘https://your.domain.uw.edu/shibboleth”. That means Shib­bo­leth is con­fig­ured to send your users over to the UW IdP. We’re almost done.

Reg­is­ter­ing with the IdP

Now you need to reg­is­ter your SP with UW and option­ally reg­is­ter your SP with InCom­mon. The UW doc­u­men­ta­tion is great here. We chose to only reg­is­ter with UW for now, so I’m not sure what the process is like with InCom­mon, but with UW it was pretty pain­less. One thing to note; You’ll need offi­cial domain access rights to reg­is­ter with UW.

After reg­is­ter­ing it takes a lit­tle while and after that the test URL should resolve to a work­ing UW webauth login form. The next steps in this post are just about get­ting Shib­bo­leth Auth set up in Drupal.

The Dru­pal Module

Now that we have Shib­bo­leth up and work­ing, we need to install the Shib­bo­leth mod­ule for Dru­pal. This mod­ule works in both Dru­pal 6 and 7. We are cur­rently using Dru­pal 6 for our pro­duc­tion site, but we have a test server up with Dru­pal 7 on it. Both are using Shib­bo­leth for auth.

This step is impor­tant and easy to miss. Add a few lines to your .htac­cess file:

AuthType Shibboleth
ShibRequireSession Off
ShibUseHeaders On
require shibboleth

Now to con­fig­ur­ing your new mod­ule. Nav­i­gate over to the shib_auth mod­ule con­fig­u­ra­tion screen at /admin/user/shib_auth. You’ll need to change these Attribute set­tings (you can ver­ify the accu­racy of these vari­ables by print­ing out $_SERVER after you are logged in via Shibboleth):

Server vari­able for user­name: HTTP_UWNETID
Server vari­able for e-mail address: HTTP_EPPN

Over on the advanced tab I also added in a URL to redi­rect to after logout. After that, all that’s left is adding the Shib­bo­leth login block to your site. This will vary by site, so I’m not going to go over that beyond men­tion­ing that the shib­bo­leth mod­ule 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 aware­ness of Shib­bo­leth, and to assure every­one that it is pos­si­ble to get it work­ing with Dru­pal on Apache in Ubuntu. It’s also for our own step by step record of how to repro­duce this in the future.