Introduction

Shibboleth is an authentication system that allows applications to verify students' netids without needing to take their passwords. Initially, this sounds silly, but it actually makes a lot of sense. If your site or application needs to know who a student is, or that they really are a duke student, all you need to do is send that request to the duke shibboleth main service. This way, a million different duke applications don't need to write their own login code or share a student's password. Plus, even insecure and untrusted apps can verify a student without worrying about security constraints.

How does this work?

Say you've made a site that only duke students should be able to access, and it prints out their name (not very useful, but oh well). Your site's main page would have a login button, which is just a link to the shibboleth-protected portion of your site. The shibboleth system then grabs ahold of the request, and sends the user to the duke login page instead. Once there, the student enters their information. If they are not successful at logging in, an error is displayed. If they log in correctly, they are redirected back to your site. Your site gets a little extra information in its Environment Variables, which you can extract in a server-side language like php or ruby. This way, displaying a user's netid is as simple as <?php print $_ENV["netid"]; ?>

How to use it

Shibboleth is a huge pain to set up, but it's really easy to use once that is done. The overall picture is that you install a bunch of junk on your server, fill out a bunch of forms, and pick a directory on your server to make secure. Once all of that is done, anything in that directory will automatically require a duke login, and any page inside that directory can access student netids and names. Pretty cool, right?

Installing

Luckily, I've whipped up a nice little script that should install shibboleth on most standard servers. It's probably a good idea to set it up BEFORE you start developing though. I can't think of anything that it could mess up, but why take any risks? To run the installer, just do git clone http://gitlab.oit.duke.edu/colab/shib-installer.git in your terminal window. This will give you a folder called 'shib-installer' with the script, 'shib-installer.sh' inside it. If you don't have git, get git! To run the script, just go into the directory and type sudo ./shib-installer.sh.

If the script didn't do it for you, or you prefer to install stuff manually, we've put together a little tutorial, linked on this page, for doing it on your own. It's an unpleasant and annoying process, but if that's your cup of tea, be my guest!

Actually using it

Whew. After all that, you're probably wondering whether shib is even worth it. It definitely is. The only thing you need to do to require a netid login for a page, is to put that page in your shibboleth secured folder. The magical shibboleth plugins on your server take care of the rest. Need to identify unique users? Just pull their netid in your serverside code! The student's netid, display name, and affiliation (student or faculty) can all be found in the page's environment variables. In php, these are accessed as an array via $_ENV, and in rails, things are a little more complex. I'd look through these pages for some more explanation.