For IT Pros This page provides a step by step quick start model for setting up your own Shibboleth service provider, to allow federated authentication to the people you choose to permit access to your services.
Before you begin:
When you set up Shibboleth access to your system, you'll be creating a service provider (SP) on your local server that communicates with at least one identity provider (IDP) elsewhere. You'll establish what information your system requests from the identity provider and what access that will provide to people who match the requested credentials.
More Shibboleth-specific terms and explanations are provided at Shibboleth, For IT Pros: Understanding Shibboleth Terms .
For your convenience, Technology Services offers localized templates for shibboleth2.xml and attribute-map.xml files. Download these files and save them in a convenient location. (You'll change a few lines later in order to specify your own Shibboleth instance and select which attributes you wish to use.)
Right-click the following links and save them as XML files:
Your Entity ID will be a string of the format https://your.host.name/shibboleth. Although it looks like a URL, it doesn't need to be one that your web server responds to with valid content. Your entity ID needs to be a string not used by other services, and it should be something that won't change.
Determine what attributes your Shibboleth-protected attributes will need to use in order to permit access to authorized users and deny access to others. This can be changed later, but you'll need to know what you want to start with.
Note: The authorization step is the responsibility of any Shibboleth-protected service. Users are usually authorized based on information, or attributes, returned to a service from Shibboleth after a successful authentication. There are as many ways to authorize a user as there are services using Shibboleth. Only you know what's best for your service. Consider who needs access to the service and how to best identify them.
Shibboleth, Authorization and Shibboleth describes how to use attributes to control access to your services.
You can look at the localized attribute-map.xml file for examples of the most commonly used attributes. (However, you probably won't need to use all of the attributes included in the file.)
Configure your webserver to support encrypted communications. Shibboleth-protected sites at the University of Illinois at Urbana-Champaign are required to operate completely over an https connection.
Install the Shibboleth SP software. You should consult the instructions for installation on your platform, including web server configuration, on the Shibboleth Project Wiki for your OS.
Generate a key and certificate to be used by your service provider to sign and encrypt data. Note that this is different from the web server certificate.
Your SP installation may have already generated these files, but it's smart to re-generate them manually to make sure appropriate values were selected.
In the below commands, your.host.name is the hostname you chose for your entityID previously. Path names will vary if you installed Shibboleth in a non-standard location. These commands will create a key and cert pair, sp-key.pem and sp-cert.pem.
cd /etc/shibboleth
./keygen.sh -h your.host.name -e https://your.host.name/shibboleth -f -y 20
(Note: On some distributions such as Ubuntu and Debian, this command may be called shib-keygen instead of keygen.sh.)
You may wish to refer to one of the following pages for more specific guidance on particular configurations.
In an Urbana campus-specific configuration, the service administrator wants to provide access to students, faculty, and staff at only the Urbana campus.
In the University-wide configuration, the service administrator wants to provide access to students, faculty, and staff at any or all of the three University of Illinois campuses, based on one or multiple group or role identities.
In the multi-university configuration, the service administrator wants to provide access to students, faculty, and staff at any of the three University of Illinois campuses as well as students, faculty, and staff at a hypothetical partner University.
It's handy to have the domain name appended to the NetID in REMOTE_USER if you'll ever be opening up your application to users outside of the university. Shibboleth best practices suggest the use of eppn or eptid instead of just a NetID without any domain name scoping. However, if it's going to be too much work to change your application to handle the domain name being included, you can request the uid attribute from the I-Trust federation registry and configure your service provider to look for that attribute when setting REMOTE_USER.
In the ApplicationDefaults section, look for the REMOTE_USER attribute. This attribute contains a list of attributes that will be used to set REMOTE_USER in the environment. The first attribute in the list that's found in the data that's returned from the IDP will be used. So, once you've requested the uid attribute, simply add it to the beginning of your list and restart shibd and your web server.
For more information on Apache's mod_shib settings, see the Shibboleth Project Wiki page, https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPApacheConfig.
Restart shibd and your web server to read your new configurations. You should already know how to restart your webserver. To restart shibd:
Register your new service provider with the necessary federation or individual identity providers.
If you did everything correctly, your Shibboleth service should now be working.
Try visiting https://your.host.name/Shibboleth.sso/Login. You will be redirected to a discovery service or a login page depending on your configuration.
Complete the login process, and you will be sent back to document root on your server.
If you receive an error, consult the native service provider troubleshooting section of the Shibboleth project Wiki at https://wiki.shibboleth.net/confluence/display/SHIB2/Troubleshooting (external link) or contact shibboleth-mgr@illinois.edu.
If you encounter any problems with testing, or if you want to check up on what Shibboleth is doing, Shibboleth offers a robust set of logs.
You can configure logging to meet your needs. This can be done with the files ending in .logger located in the same directory as your shibboleth2.xml. The log facilities that you can configure are:
For specifics on configuring these logs, see the comments in shibd.logger and configure as needed. The defaults are probably fine for most setups. A syslog.logger and console.logger are also available if you prefer.
Now that your service provider is working, you'll want to put your application behind it. This means consuming the attributes that you requested into your application so you can use them.
AuthType shibboleth ShibRequestSetting requireSession 1 # Authentication required ShibRequestSetting shibUseEnvironment 1 # Pass returned attributes as environment vars require valid-user
More complex configurations and many other options can be found in the Shibboleth project Wiki.