Using Shibboleth

Shibboleth is software that allows one website to use another website for login information so that people who want to log in to a Shibboleth site are transparently redirected to a central login site to enter their account name and password and then sent back to the original site along with their login credentials. This means that people don't have to remember individual login information for each site they want to access, and the individual sites don't have access to the person's password.

This page describes how to use the Shibboleth resources available within the Computer Science department on your own webpages. For information about logging in to a site that uses Shibboleth, see Shibboleth.

Terminology

Shibboleth has a few terms that is uses for specific parts of the software. The central server that allows people to log in is called an Identity Provider or IdP. The web server that wants to use those login credentials is called a Service Provider or SP. Every IdP and SP is uniquely identified by its EntityID. An EntityID looks like a URL (the main CS webserver's EntityID is https://www.cs.jhu.edu/shibboleth), but it doesn't have to actually go to a website.

Shibboleth only provides authentication, which means that it provides a trusted source of account names. Shibboleth provides information that is equivalent to saying things like "the person at this browser has proven that they own the JHED ID that I will tell you about." It is up to you to configure your own authorization and determine which JHED IDs and CS accounts will be allowed to access your webpages.

Shibboleth Servers Available in CS

Johns Hopkins operates an IdP that allows logins with JHED IDs. If you want to set up your own server to use the JHU IdP, you'll have to contact the Enterprise Auth team, but our webserver (www.cs.jhu.edu) is already set up to use JHED IDs, so websites hosted there only need the configuration documented below.

The CS department runs an IdP for logins using CS Grad Net accounts. If you want to run your own web server that uses CS accounts, please contact support@cs.jhu.edu for assistance. The CS department webserver (www.cs.jhu.edu) is already set up to use CS Grad Net accounts, so websites hosted there only need the configuration documented below.

The CS department's webserver (www.cs.jhu.edu) is configured as an SP for both JHED and CS Grad Net accounts.

Account Information

Shibboleth provides a bit of information about the logged-in account, but the provided information differs between JHED and CS accounts. One thing that's the same for both is the username, which is provided in the REMOTE_USER CGI environment variable.

If a person logs in via JHED, their REMOTE_USER username will be their JHED ID followed by "@johnshopkins.edu". Thus, a person with a JHED ID of "jdoe1" would be identified as "jdoe1@johnshopkins.edu".

If a person logs in via a CS Grad Net account, their REMOTE_USER username will be their CS Grad Net account name followed by "@cs.jhu.edu". Thus, a person with a CS Grad Net account name of "janedoe" would be identified as "janedoe@cs.jhu.edu".

How to Use the www.cs.jhu.edu SP

You have two choices about how to use Shibboleth with your www.cs.jhu.edu webpages.

The first option is to put all of the authorization into a .htaccess file and let the webserver manage everything. With this option, the webserver itself will determine who is allows to see your pages. If you want to protect plain HTML files (i.e. you're not using CGI, PHP or something similar), this is the only option available to you. Even if you have dynamic content, your programs don't have to know anything about logins or authorization.

The second option is to tell the webserver that you want Shibboleth available but that your programs will decide what to do with the Shibboleth login information. This option can be more difficult to set up, but it gives you more flexibility in your treatment of the information you get from Shibboleth.

Option One: Webserver Authorization

You need to create a file named .htaccess in the top level directory where you want to restrict access. For example, if you wanted to require logins for any page under http://www.cs.jhu.edu/~account/secret, you would create the file as ~/public_html/secret/.htaccess. Unless you simply want to give anyone with a JHED or CS account access, you'll also need to make a file named .htgroup that contains a group name and the accounts that should be members of that allowed group.

The .htaccess file should contain the following:

# The following rules ensure that the website is only accessed via HTTPS.  This
# is needed only because the IdPs only know about https://www.cs.jhu.edu; if you
# initiate Shibboleth authentication from HTTP, you'll get an error from the
# IdP.
RewriteEngine On
RewriteCond %{HTTPS} off
RewriteRule (.*) https://%{SERVER_NAME}%{REQUEST_URI} [R,L]

# The next part activates Shibboleth
AuthType Shibboleth
ShibCompatWith24 On

# This requires everyone to log in before they can see the protected pages.  If
# you don't have this line, people still won't be able to see the pages, but
# they won't be prompted to log in, so they'd have no way to get access.
ShibRequestSetting requireSession 1

# In order to access the pages, the person must be a member of the group named
# "allowed".  You can use a different name for the group if you prefer; just
# make sure the group name matches what's in the .htgroup file.
Require group allowed

# This is the file that contains the definition of the "allowed" group.  The
# path name must be fully qualified, so replace "<account>" with your account
# name.  The file doesn't have to be under ~/public_html (and it's generally
# recommended that it go elsewhere) but putting it here simplifies the
# permissions necessary for the webserver to see it.
AuthGroupFile /users/<account>/public_html/secret/.htgroup

# This ensures that no one can see the contents of the group file.
<Files .htgroup>
    Order Deny,Allow
    Deny from all
</Files>

If the people with JHED IDs jdoe1 and fbar3 should be given access as well as the person with CS account mumble, put the following into ~/public_html/secret/.htgroup:

allowed: jdoe1@johnshopkins.edu fbar3@johnshopkins.edu mumble@cs.jhu.edu

The format of the file is described in the Apache AuthGroupFile directive.

When you're done, set the appropriate permissions on the files with the following command from the command line in the directory where you've saved them:

chmod 0604 .htaccess .htgroup

Using Only JHED IDs

If you only want to use JHED IDs (and not CS accounts), add this to your .htaccess file:

ShibRequestSetting entityID https://shibboleth.jh.edu/idp/shibboleth

Using Only CS Accounts

If you only want to use CS Grad Net accounts (and not JHED IDs), add this to your .htaccess file:

ShibRequestSetting entityID https://gidp.cs.jhu.edu/idp/shibboleth

Option Two: Web Application Authorization

Instructions coming soon!