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-based site are transparently redirected to a central login site to enter their account name and password and are 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 people's passwords.
(In JHU terms, for example, a webpage hosted on www.cs.jhu.edu, the CS Department webserver, could request that a visitor log in using his or her JHED credentials. The CS webserver would direct the visitor's browser over to JHU's login servers, which would then approve the login and send the browser back to the original webpage. The CS-based webpage would then receive the JHED login information without actually having to know anything about the person's JHED password or details of the login. Shibboleth also allows CS webpages to permit logins with either CS or JHED credentials.)
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 data, 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".
Session Length
Once someone logs into a CS-hosted webpage via Shibboleth, the CS webserver establishes a session to remember the login. So long as the session exists, the person will be able to continue accessing Shibboleth-protected pages without having to log in again.
Sessions are removed after one of two things occurs:
- Two hours pass without any activity from the logged-in person (i.e. the person didn't access any pages for two hours)
- Eight hours pass since the person's most recent login
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 www.cs.jhu.edu webserver manage everything. With this option, the webserver itself will determine who is allowed 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 if you use this authorization approach.
The second option is to tell the www.cs.jhu.edu 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
Under public_html, 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:
# This activates shibboleth
AuthType Shibboleth
<IfVersion < 2.4>
ShibCompatWith24 On
</IfVersion>
# Shibboleth only works if the webpage is accessed via HTTPS (not HTTP). The
# following setting will redirect any clients from HTTP to HTTPS so that logins
# will always work. (If you don't use this and someone accesses the page via
# HTTP, they'll get a "No peer endpoint available to which to send SAML
# response" error message from the IdP.)
ShibRequestSetting redirectToSSL 443
# 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>
Your .htgroup file contents will vary more depending on who you need to give access to. To continue the above example, 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
By default, people logging into your site will be able to choose whether to use JHED or CS accounts. If you only want them to use JHED IDs, add this line anywhere in your .htaccess file:
ShibRequestSetting entityID https://login.jh.edu/idp/shibboleth
Using Only CS Accounts
By default, people logging into your site will be able to choose whether to use JHED or CS accounts. If you only want them to use CS Grad Net accounts, add this line anywhere in your .htaccess file:
ShibRequestSetting entityID https://gidp.cs.jhu.edu/idp/shibboleth
Option Two: Web Application Authorization
There is a lot more potential variation for this option, so only the most general information can be covered. If you need further assistance, please email support@cs.jhu.edu with your questions.
At the very least, you will need a .htaccess file in the root directory of your web application. In it you will need at least the following directives:
AuthType shibboleth <IfVersion < 2.4> ShibCompatWith24 On </IfVersion> Require shibboleth
Those will make Shibboleth information available to the application, but will not restrict access or even trigger Shibboleth authentication. (If you want to require Shibboleth authentication, add a line containing ShibRequestSetting requireSession 1.)
Custom Programming
If you're writing your own application, all you really need is to look at the contents of the REMOTE_USER environment variable to get the authenticated username (as described above). The particulars of how you grant access based on that username are up to you.
Logins
To trigger a login, direct the person on the website to the URL https://www.cs.jhu.edu/Shibboleth.sso/Login. (Obviously, if your page is already being accessed on https://www.cs.jhu.edu you don't need the protocol and hostname in your link.)
There are a few URL parameters you can use in conjunction with this. The target parameter gives the URL that the person should return to after logging in. If you don't use this, they'll be returned to the main https://www.cs.jhu.edu page, which is almost certainly not what you want.
The entityID parameter can be used to pick either JHED or CS as your authentication source (rather than allowing visitors to choose from between them, which is the default). Set entityID to https://login.jh.edu/idp/shibboleth for JHED IDs and https://gidp.cs.jhu.edu/idp/shibboleth for CS Grad Net accounts.
As an example, here's a link that would use only JHED IDs and would return people to https://www.cs.jhu.edu/~example/myapp after they've logged in:
https://www.cs.jhu.edu/Shibboleth.sso/Login?target=https://www.cs.jhu.edu/~example/myapp&entityID=https://login.jh.edu/idp/shibboleth
Logouts
We recommend that you not use explicit logouts and instead just rely on the implicit length of sessions in the SP and IdP. The concept of "logging out of Shibboleth" is a surprisingly complicated one, for reasons sketched out on the Shibboleth page (and detailed on the Shibboleth wiki's Single Logout Issues page).
If, despite the above, you really want to have a logout link in your webapp, you can link to https://www.cs.jhu.edu/Shibboleth.sso/Logout. That link takes at least one URL parameter: return gives a URL to which the person logging out may be sent after logout. As of March 2014, neither JHED nor CS uses that parameter, but it's useful to include it in case the Shibboleth implementations are changed in the future.
Integration with Other Applications
If you're using a third-party program, like MediaWiki or WordPress, you'll have to see if there are existing plugins or documentation for Shibboleth. You can also email support@cs.jhu.edu for assistance; the IT group has experience with Shibboleth integration for at least MediaWiki and DokuWiki.