Shibboleth, Protecting Your Applications with Shibboleth
For IT Pros This page contains information about Shibboleth, SAML2-compliant single sign-on technology that is available to campus IT Professionals for the protection of their online applications and resources. If you are an end-user, please contact your IT Professional with any questions that you may have about this service.
NOTE: Shibboleth is a security software package that IT service administrators can use to grant end-users access to protected online resources in a privacy-protecting manner. This documentation assumes that you are a campus IT service administrator who wishes to learn more about using Shibboleth. It also assumes that you already understand essential web server and web application concepts and terminology. This documentation will focus on an explanation of Shibboleth itself rather than an explanation of web server or web application concepts.
Shibboleth is an opensource, community-supported, SAML2-compliant web single sign-on solution. It’s the basis of our federated single sign-on solution at the University of Illinois. The use of the SAML2 standard makes it easy to plug into many opensource and commercial web applications. Built-in Federation Support makes it ideal when an application needs to be available to users from multiple campuses (or even other institutions).
Shibboleth, as a sign-on technology, is appropriate in the following cases:
- If you run an application that will be federated -- that will be used by students, staff or faculty from other colleges and universities -- Shibboleth will inter-operate with those institutions for easy authentication.
- If your application supports SAML2 out-of-the-box, choosing Shibboleth for web sign-on will save you time and effort.
- If your application requires multi-factor authentication, you should use Shibboleth: Other university web SSOs currently don’t have multi-factor auth in place.
Every server running Shibboleth-protected content is known as a service provider or SP. The server either uses proprietary SAML2 code to initiate the sign-on process or runs the free SP software from the .
The SP communicates with at least one identity provider or IDP. Each institution runs an IDP to perform the authentication process and to return the information about a logged-in user to the SP. At this university, we run three IDPs currently: one for each of the three University of Illinois campuses. If you need to allow users into your application from all three campuses, you will need to establish a trust relationship with all three IDPs. Additional user-bases from other universities will require additional trust relationships.
Trust relationships are achieved by exchanging metadata: information in XML format that includes the unique identifier (entity ID) for your SP, how to communicate with it, and certificates for signing and encrypting information passed to it.
A federation makes it easy to establish a trust relationship with many IDPs. A federation is a group of organizations that have pre-established policies of trust for authenticating users and releasing information about those users to one another. We participate in two federations: The I-Trust federation is a federation of the three University of Illinois campuses and may extend to other Illinois institutions in the future. The InCommon Federation is comprised of education, research, and business entities throughout the United States. If you need to allow access to resources beyond the university, you’ll want to participate in InCommon. Note that being in a federation doesn’t mean you must allow access to all users from organizations in that federation. Rather, it means you have the option of allowing users from any of those organizations in. You can choose, within a federation, which organizations are permitted access.
A service that allows users from only one organization, such as the Urbana campus, needs only to redirect users to that organization’s IDP on login. If your application allows users from more than one organization, though, you need to redirect users to a Discovery Service: a web page that allows a user to select their home organization. Centralized Discovery Services are available that list all organizations in InCommon and I-Trust. If you’d rather not have organizations listed who aren’t allowed access to your organization, though, it’s not complicated to create your own Discovery Service page.
If your application has built-in SP support and handles the SAML2 communications with the IDP, you can skip to Configuring your SP. You will need to install the Shibboleth SP on your server if you’re writing your own code and want to simplify authentication or if you have existing software that can consume authentication information from HTTP header variables or environment variables.
The Shibboleth SP is available as pre-built binaries as an RPM or as a Windows installation package. The software is also available from source. The software can be downloaded from http://shibboleth.net/downloads.
Shibboleth Project Wiki Installation Instructions
If you’re using the RPM or Windows installer, installation is straightforward. Regardless, you should consult the instructions for installation on your platform, including web server configuration, on the Shibboleth Project Wiki for your OS:
Solaris and other operating systems not mentioned above require building from source. See build instructions at https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPSolarisInstall
Complete the installation for your platform using its Shibboleth Wiki (above).
The following sections deal with specific configuration items for the SP once you have installed it.
The heart of your SP configuration is in shibboleth2.xml, located by default in /etc/shibboleth on Linux and Unix systems. Most of the changes you’ll need to make specific to the university’s Shibboleth environment will be in this file.
- Choose your SP’s entity ID. Entity IDs take the
form of a URL (e.g.: "https://some.host.illinois.edu/shibboleth"). Note
that you don’t actually have to have content at /shibboleth on your
webserver. The hostname part of the entity ID should be chosen as
- If your system just has a single hostname that the web server answers to, use that hostname.
- If the web server answers to a different hostname than the system’s primary hostname, use the web server hostname.
- If the web server will be hosting multiple hostnames with content protected by Shibboleth, use the hostname associated with whichever service is the primary one.
- If there is no primary service, you’re generally safe using the system’s actual hostname, though this might make things difficult in the future if you migrate these services to a different server.
- Tell your SP which IDP or Discovery Service to use.
This is set using the SSO section of shibboleth2.xml. If you’ll only be
allowing users from the Urbana campus, set EntityID to urn:mace:incommon:uiuc.edu and set discoveryURL to an empty value of “”. To allow users from all three campuses, make entityID empty (set it to “”) and set discoveryURL to https://discovery.illinois.edu/discovery/DS.
If you want to offer your own set of organizations to your users such
as a subset of InCommon, you will need to set up your own discovery
service and configure it here. This is explained later.
- You’ll also need to consume metadata for the IDP or IDPs you’ll be communicating with.
You should consume the metadata for whichever federation you’re joining
your SP to. See the following section for help on making this decision.
- Most services will need the I-Trust metadata.
- SPs communicating with other universities will probably need the InCommon metadata.
Metadata consumption is defined using the MetadataProvider section of shibboleth2.xml. The metadataProvider element needs a uri attribute set to the URL of the metadata and a backingFile attribute set to the name of a file on disk where a cached copy of metadata can be stored. The backingFile attribute can be changed as you wish. This is the local copy of the metadata that will be saved to your server, so it should be named such that you know what the file that the SP creates actually is.
- For I-Trust, set the uri to .
- For InCommon metadata, set the uri to .
- You’ll also need to obtain the signing certificate for the federation metadata so that your SP can use it to validate the data. You can do this with your web browser or any command-line web tool such as curl or wget.
- For I-Trust, download https://discovery.itrust.illinois.edu/itrust-certs/itrust.pem.
- For InCommon, download http://md.incommon.org/certs/inc-md-cert.pem and verify the cert correctness using the instructions at https://spaces.internet2.edu/display/InCFederation/Metadata+Signing+Certificate
Place this file in the same directory as your shibboleth2.xml and update the certificate attribute for the MetadataFilter with type=”Signature” to match that of the file you downloaded.
- 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:
- shibd_log for shibd messages
- native_log for basic operations, and
- tran_log for logging of the attributes (but not the values) that your SP receives from an IDP.
Values are never logged for security reasons. 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.
- Set up your Shibboleth attribute map. This file maps the attributes such as name, email, user ID and affiliation that the IDP sends upon a successful login to your SP into names that your application can consume.
Check additional attributes along with the NetID: It’s extremely important that you request enough information about users from the IDP and consume it into your application to perform good authorization. You should never assume that, just because a user was able to log in, they should be allowed in. This may mean simply making sure the user has a valid NetID or is from the right campus, or it may mean checking their affiliation with the university or their department. All of this is available from the IDP as attributes.
Enable the attributes you need, and don't enable attributes you don't need: If an attribute isn’t mapped here, the SP will ignore it. So it’s important to have every attribute that you’ll receive listed and uncommented. Uncommenting unnecessary attributes can slow down your SP, though. So don’t uncomment more than you need. The attribute-map.xml that was installed with the SP contains most standard attributes and can be assumed to be available from most InCommon-participating IDPs. There are additional attributes available from I-Trust participants that can be requested from the I-Trust federation registry. Most information available from the campus electronic directory can be sent to your SP, allowing you to skip doing a separate directory query after a user logs in. If you need something that you don’t see listed in the I-Trust federation registry, just ask the Shibboleth service managers.
Special attributes: Eppn, also known as eduPersonPrincipalName, is the user’s NetID with their home institution appended to it, such as firstname.lastname@example.org. This should be used instead of just the NetID (known to Shibboleth as uid) when possible. If you use uid and allow logins from multiple organizations now or in the future, you may have problems if the same NetID is used by different people from different organizations. The @domain.edu helps make it unique. Additionally, if you don’t need to know the user’s exact identity but need a unique identifier, eptid, also known as eduPersonTargetedID, should be used. This is a non-human-readable string that’s guaranteed to be a unique combination of the SP, the IDP, and the user. Definitions for both of these attributes are available in the attribute-map.xml.
Note, too, that there are SAML1 and SAML2 attribute definitions in the distributed shibboleth2.xml. In the vast majority of cases, and unless a Shibboleth service manager tells you otherwise, you won’t need SAML1 attribute definitions. The ones that contain a numeric OID, a string of numbers and periods, are SAML2 definitions and are the ones you should use.
- Generate a certificate for your SP. This
certificate will be used by the SP, not the web server, to sign and
encrypt communications with the IDP. It can be a self-signed
certificate, but if you want to purchase a certificate, you can do so.
We recommend using a self-signed certificate generated with the keygen.sh (keygen.bat on Windows) script as follows:
</etc/shibboleth/keygen.sh -o /etc/shibboleth -h entityid.hostname.illinois.edu
Substitute the hostname used in your entity ID for the value of the -h switch. This command will create sp-key.pem and sp-cert.pem in your /etc/shibboleth directory which is the default location configured in shibboleth2.xml where the SP looks for these files.
Your SP is now configured enough for basic operations. Restart your web server and the shibd service to re-read your configuration.
Joining a Federation
Now that your service provider is configured, you need to let one or more identity provider know about it. This means sharing your SP’s certificate and endpoint URLs so that users can authenticate with Shibboleth and their information can be passed back to your service. How you federate your service provider depends on who needs to be able to log in. You probably only need one of the following options, but there’s no reason you can’t choose more than one if the need arises.
The I-Trust Federation
Currently, I-Trust is comprised of the three University of Illinois campuses and is ideal for services that are limited to University of Illinois users but that aren’t appropriate for CA SiteMinder. If your service fits into this category, registering a new service in I-Trust is easy. Just follow the instructions on Establishing Your Service in the I-Trust Federation. Once your service provider is approved and you’ve added the I-Trust metadata to your configuration, users from all three campuses will be able to log in within a few hours.
The InCommon Federation
If you need to federate with other higher-ed institutions in the United States, you can publish information about your service in InCommon. This makes your service available to several hundred organizations around the country. Make sure, if you choose this option, to limit access to the organizations who are allowed to use the service. It’s recommended, if you need to federate beyond the University of Illinois, that you first join I-Trust and ensure that everything’s working. Once it is, contact the Shibboleth service managers at email@example.com and explain your need to join InCommon. They will then sponsor your InCommon registration and work with you to publish your service.
Federating with Other Institutions
In rare cases, you may need users from an institution neither in I-Trust or InCommon to have access to your service. Smaller schools or international organizations are both good examples of this. If this describes your service, you’ll need to manually generate metadata that describes your service and send it to the IDP operator for that organization. Before doing this, ask if the organization is a member of another federation and if they’d be willing to sponsor your registration in that federation. Joining a federation is much cleaner and more secure than manually sharing metadata and should always be the preferred option. If, however, your only choice is to manually share metadata, the following sections explain how to generate it. Send the results to the IDP operator at the institution you’re federating with along with a list of attributes you need supplied. Make sure to check and see if that institution has any other requirements for federating with your service provider.
Manually generate metadata on Unix
If you’re on Unix, you can manually generate metadata using the /etc/shibboleth/metagen.sh script. If the hostname in your entity ID is also one of the hostnames that your web server answers to, run:
/etc/shibboleth/metagen.sh -c /etc/shibboleth/sp-cert.pem -h entityid.hostname.illinois.edu >metadata.xml
Add more –h flags followed by the hostnames configured in your web server to represent each hostname that will have Shibboleth-protected applications on your server. Each hostname that users will be visiting requiring Shibboleth authentication must be listed or the IDP will not send responses back. Always list the hostname used for your entity ID first, as this hostname is used to generate the entity ID in the metadata.
If you’re using a system hostname not used by your web server as your entity ID, you’ll need to add the -e option to the above command:
/etc/shibboleth/metagen.sh -c /etc/shibboleth/sp-cert.pem -e https://entity.id.illinois.edu/shibboleth -h some.hostname.illinois.edu >metadata.xml
As above, add more –h flags if you have multiple hostnames hosted by your web server that will need Shibboleth authentication.
Manually generate metadata on Windows
The Windows SP doesn’t include a metagen.sh. Instead, use your web browser or a command-line web tool to retrieve your metadata from the metadata handler at . You may need to modify hostnames in the generated XML. Look through this file and ensure that location attributes for each assertionConsumerService matches the hostname your web server answers to. If your web server answers to multiple hostnames, copy these elements so that you have a set for each hostname that Shibboleth needs to know about.
Once you've federated your service provider, you can proceed with consuming data from Shibboleth.
Shibboleth attributes can be passed to your application with environment variables or HTTP headers. Environment variables are recommended for security, but this option is not available using IIS. Once your application has the attributes it needs, you can do pretty much anything you need to do from here.
You can find some great information about shibbolizing your applications on the Shibboleth Project Wiki page, https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPEnableApplication.
Java application developers may wish to read the page specific to protecting Java-based applications, https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPJavaInstall.
Other good docs on protecting content and initiating a session can be found in the Native Service Provider section of the Shibboleth Project Wiki configuration page, https://wiki.shibboleth.net/confluence/display/SHIB2/Configuration.
More advanced concepts are discussed elsewhere in the documentation on the Shibboleth Project Wiki and are beyond the scope of this documentation.
Assigning uid to REMOTE_USER
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.
If you need to allow users from more than one organization to log into your application, you’ll need to redirect them to a discovery service to select their home organization before logging in.
Federation-Wide Centralized Discovery Services
If you want them to be able to choose from all of the IDPs in your federation (InCommon or I-Trust), you should use that federation’s discovery service -- and there’ll no need to run your own. You can always whitelist or blacklist specific IDPs if you don’t want to accept users from everyone in the federation but don’t mind their IDPs being listed on the discovery service page.
For information on the whitelist and blacklist metadata filters, see https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPMetadataFilter#NativeSPMetadataFilter-WhitelistMetadataFilter.
Local Discovery Services
If you want your discovery service page to only contain the organizations from which you allow users, you’ll need to set up your own discovery service. Thankfully, this is not difficult.
You have three options:
- Static web page: In its simplest form, a discovery
service is just a series of links back to the SP’s discovery response
URL with the entity ID of the selected IDP appended as a request
variable named, appropriately, entityID. If your SP only hosts
applications and content on one Shibboleth-protected hostname, or if
you’re willing to maintain multiple pages or write a little dynamic code
to grab the HTTP referer, you can whip up a very simple discovery
service. Links would look like the following:
- You would configure your discoveryURL in your shibboleth2.xml’s SSO section to point to your static page.
- The user’s browser would return them to your SP, this time with an IDP selected, and your SP would immediately direct them to that IDP to log in.
Note that the IDP’s entityID in the link must be URL-encoded. You can find the entityIDs of all IDPs in your federation in the federation metadata file that your SP consumes. The format of the UIUC IDP above is an older format. Most IDPs use a newer format that looks like a URL just like your SP’s entity ID.
Combining this method with the previously mentioned whitelist metadata filter ensures that your users will only see those IDPs listed on your discovery service page and that your SP only knows about the IDPs that you accept.
Make sure to redirect the users back to the hostname that they originally visited from your discovery service page, as well.
- The Shibboleth Project’s Embedded Discovery Service:
the work of parsing the metadata and pulling out all of the needed
information on IDPs for you. You simply provide it with a list of
entityIDs to allow or deny, and it generates a page including the
organization names and, when available, even their logos. If you want
something slightly more automated than the manual method, this is a very
nice solution, and is easy to configure.
For details and where to download this service, see http://shibboleth.net/products/embedded-discovery-service.html.
- The Shibboleth Centralized Discovery Service: The heaviest weight option is generally not recommended unless neither of the above methods work for you. This option is generally used by federations to operate a federation-wide discovery service. It’s a Tomcat-based Java application that, though quite flexible, requires quite a bit of configuration. If the above options won’t work for you and you’re willing to run Tomcat for a discovery service, download, installation and configuration instructions are available at http://shibboleth.net/products/centralized-discovery-service.html.
As noted throughout this document, the Shibboleth Project Wiki at is an excellent resource for configuration and troubleshooting. If you can’t find what you need there, you’re welcome to email the Shibboleth service managers at firstname.lastname@example.org. The Shibboleth community can help when we can’t. See below for information on subscribing to the Shibboleth users list.
The Shibboleth service managers will try to advise SP operators of important Shibboleth changes through the UIUC Shibboleth Announce list. Anyone who’s an SP administrator in the I-Trust federation registry from the Urbana campus will be added to this list automatically. Others are welcome to subscribe, as well, by sending an email to email@example.com with the text “subscribe shibboleth-announce” in the message body.
In addition to the UIUC Shibboleth list, we also recommend you subscribe to the Shibboleth Announcements mailing list to learn of such advisories directly from the Shibboleth Project Team. In addition to the announcement list, there are also lists for general discussion and questions and for Shibboleth project development.For information on subscribing to these mailing lists, see .