This document explains how to set up a Shibboleth Service Provider (SP) and integrate it with MyAccess. Even though this is for setting up with MyAccess, the steps are the same for integrating with any Identity Provider (IdP).
This document only covers installing a SP on CentOS (which is similar to RHEL) machine, i.e., it does not cover setting up a SP on Windows. With that said, parts of the configuration of the SP should apply equally to Windows as well as other platforms. It also assumes that you are using Apache 2.2.x.
Install the SP (shibd)
This document is about installing
shibd, the C program which runs as its own service on the server. In this case,
shibd is Shibboleth, i.e., the "Service Provider".
Install with yum
It is recommended that you install the SP via yum, as it will be easy to update the software when there are any security fixes, upgrades, etc.
Before you can use yum, you need to download a .repo file containing the info about where Shibboleth is located. Get the .repo file for your OS here:
And place the file in:
Once you have done that, you can install shibd.
If the above does not work (it did not work for me because yum was looking for versions of files that did not exist in the repo), then you can install it manually.
The remaining install instructions are assuming 64bit install on CentOS 5. If this is not your platform, be sure to adjust the commands as appropriate.
If installing manually, you need to install the uxixODBC devel package as log4shib requires this package be installed first:
Next, download the RPMs into a directory (I recommend that you create a directory just for these RPMs as it will make the install command easy):
Once the files have been downloaded, install them as follows:
Now, you can verify that shibboleth has been installed:
and you should get output that looks something like this:
Make Sure shibd Runs at Startup
Now, to make sure
shibd runs at system startup time, type the following commands (check with your local sys admins fist to be sure this is OK with them):
To make sure
shibd is configured properly, type the following:
The output should look like this:
Important notes about configuration can be read here:
Once that is done, then come back to this section for further configuration information.
The install process places all Shibboleth-related configuration files into
/etc/shibboleth. The files in this directory that you will be editing are:
/etc/httpd/conf.d/shib.conf to protect resources by Shibboleth. For instance, the Library manages the CLE, which only has one page that needs to be protected (as application-level security takes care of regular session management), so the config for this application is:
Now, when a user tries to go to the URI
/auth/shibboleth/index.php with their browser, Shibboleth (
shibd) will intercept it and make sure the user is authenticated.
All files ending in
.conf which are located in the
conf.d directory are automatically added to the Apache config when Apache is started. If you are not using the standard CentOS-installed Apache, then you can configure /etc/shibboleth/apache22.config, and then include this file into your Apache config by adding the following to the bottom of your httpd.conf file:
In order for Shibboleth to work properly, Apache has to have the proper hostname configured. So, either in the main
httpd.conf or in the vhost section, make sure
ServerName is the actual hostname of the service, without the port number. So, if the service name is host.subdomain.ucsf.edu, then the
ServerName line should look like this:
Shibboleth also requires that
UseCanonicalName be set to on, so that line in
httpd.conf should look look like this:
Once the Apache changes have been made, do an Apache
configtest to make sure all is well, and if so, restart Apache.
MyAccess (and other IdPs) will send your application attributes which you ask them to send (this is a process where you ask the MyAccess personelle to configure their IdP to do this for you, i.e., there is no programatic way to get back attributes that your SP is not authorized to get back, so you have to ask for them and they have to configure the IdP to pass them to your SP).
Again, using the CLE as an example, we get back the following attributes from MyAccess:
- eduPersonPrincipalName (eppn)
- sn (surname)
attribute-map.xml, uncomment the following lines:
Below those attributes, add the following attributes:
Since this is an XML document, comments are made with <!- and -> marks, so be sure to close any comment that you open.
Next, uncomment the OID versions of these attributes:
And then add the following below those attributes:
If you need other attributes, then you will need to consult with MyAccess for the names of the attributes, and the OIDs used for them.
eppn) is configured by default, as this is the attribute which most IdPs assert, by default, about an individual. So you do not need to uncomment it.
shibboleth2.xml is where most of the configuration goes, and this is where everything will start to make sense.
Next, find the line that begins with:
This needs to be edited with the
entityID of your SP, which will be in the form:
You should be using the same hostname as you used above. And yes, you need to be using SSL!
You will also note the attribute
REMOTE_USER, which is the HTTP
shibd daemon populates the
REMOTE_USER header with the value of
At UCSF, the value for
eduPersonPrincipalName is made up using part of a person's UCSF ID Number, with
@ucsf.edu appended. For example, if your ID Number is 021234567, then your
eduPersonPrincipalName will be email@example.com.
In this same section, you want to edit the
SSO attribute for the MyAccess (test) IdP.
Find the section that looks like this:
Change it to look like this:
Of course, change
dp.ucsf.edu if you are integrating with production.
Also, if you are using a discovery service, just like the note states in the XML above the
SSO attribute, remove the value for
entityID, and put the URL of your discovery service as the value for
Ask MyAccess for a copy of their test IdP Metadata file. Once you get it, put it in
/etc/shibbolth, so something like this:
Now, back in the
/etc/shibboleth/shibboleth2.xml file, find the section that begins with "Example of locally maintained metadata.", as this is where you will be putting information about the MyAccess metadata (for their test and or production IdP), and the InCommon metadata (if you need to use the InCommon metadata).
Add an entry for the MyAccess metadata file:
If you need this SP to interact with an IdP that is part of InCommon (like the production MyAccess IdP), then add a provider for the InCommon metadata file. Since this is detailed on the InCommon section of the Internet2 wiki, I will not repeat it here:
Now that all of this is configured, you can start the
shibd daemon. On Linux you do this using the following command:
shibd logs things to the following two files:
shibd does not start, then you will want to tail the
shibd.log file to see where the error is located. Most likely it will be because of an XML error (like forgetting to close a comment).
Your SP Metadata
Just like an IdP, your SP also has its own metadata, and in order for IdPs to be able to trust your SP and sign information specifically for the SP, it needs the SPs metadata.
If this SP is going to allow users from other institutions, i.e., users who are not using MyAccess for authentication, then you need to request that MyAccess register your SP with InCommon. For production this is a must. For instance, if you want people for LBNL to use your SP, then MyAccess needs to register your SP with InCommon so that the LBNL IdP gets your metadata when its metadata file refreshes.
You can access your SP metadata by going to this URL:
Of course, replace
hostname with the hostname of your server.
If you can successfully download the metadata, then you know
shibd is running correctly.
Shibboleth supports logout from the SP and the ability to be sent to a location after logout, like an IdP logout page if the IdP supports logout. The MyAccess IdP has a logout page which will end the IdP (SSO) session for the user at the IdP itself. In other words, if a browser is redirected to this URL the browser will be forced to log into Shibboleth the next time the user tries to log into a Shibboleth-protected service and the user does not already have a session established with that service. So, existing sessions at other SPs are still valid, but any new session would require authentication.
Edit MyAccess Metadata
To enable logout for the MyAccess IdP, add the following the MyAccess IdP metadata (in the IDPSSODescriptor section):
Also, if you want the MyAccess IdP logout page to display a URL which the user can use to return to the application, you can add a
url= param to the end of
shib_logout.jsp. So, if we want to return to the wiki, we would do this:
dp.ucsf.edu if you are integrating with production.
If you are using more than one IdP for login to your application and each IdP supports logout, then if there is a
SingleLogoutService present in the metadata for the IdP, the
shibd process will send the user to the correct location when the browser is sent to
In order for the above logout mechanism to work for the IdP, the following must be configured in the
Sessions section of
Integrate With MyAccess
At this point you are ready to integrate with MyAccess. You should open up a service ticket with ITS (http://help.ucsf.edu/ then click on "Submit a ticket for ITS or School of Nursing IT") and include the following information:
- Subject indicating that the request is for "MyAccess Shibboleth [test or production]"
- Attributes you want to get back from their IdP (and if you want ones that were not covered above, then you need to ask them for the OID for the attribute and configure it in
- URL for your metadata (so that they can download the metadata, or attach the metadata file to the ticket)
If you have not done so already, ask them to send you their test IdP metadata and place it in the location which we covered above.
Test Your SP
Once you have the above set up, you can test
shibd without even having an application configured to use Shibboleth. Just create a simple form on your shibbolized webserver that looks like this:
Of course, replace
hostname with the hostname of your server and
uri-you-protected-in-apache22.config with the actual URI that you put into
apache22.config. If you did not protect a URI in
apache22.config, then do that now, and restart Apache.
Now, tail the following file:
And then submit the form. If all goes well, you will be forced to authenticate against the MyAccess test IdP, and once that is successful, you will be back on your server, and the
transaction.log file should have something like this in it:
If you do not see the this, then there is something wrong with the configuration. Check the
shibd.log file for more information.