Shibboleth, Multi-university configuration
For IT Pros This page provides additional information on how to configure your Shibboleth installation in order to restrict access to members of the Urbana campus only.
The desired situation
You want to use Shibboleth to allow both U of I members and members of other universities access to your site, while restricting it from non-University use.
At this point, you should have completed steps 1 through 5 in Shibboleth, Setting up a Service Provider .
This page explains step 6 (configuration) in more detail.
If you want to allow many universities to participate, your best option is to use InCommon as your source.
NOTE: It may be easiest for you to start with an Urbana-only or University of Illinois-only configuration and make the initial setup work with iTrust before changing to InCommon to gather other universities' information.
(If you want to allow only a select few universities to participate, see the "Run a Discovery Service" headline below.)
If you haven't completed the QuickStart steps 6a.1 and 6a.2 yet, open your localized shibboleth2.xml in a text editor and make the following changes.
In the line:
<ApplicationDefaults entityID="https://host.name.illinois.edu/shibboleth" REMOTE_USER="eppn persistent-id targeted-id">:
- Replace https://host.name.illinois.edu/shibboleth with the entity ID you chose previously.
In the line:
<Errors supportContact="firstname.lastname@example.org" helpLocation="/about.html" styleSheet="/shibboleth-sp/main.css"/>
- Replace email@example.com with the appropriate support email address for services on this server.
- Replace /about.html with the path to your help pages.
- Replace /shibboleth-sp/main.css with the path to the CSS file used for your Shibboleth error templates, if any.
Next, in the section that says:
<!-- Below setting will use Urbana campus IDP only. --> <SSO entityID="urn:mace:incommon:uiuc.edu" discoveryProtocol="SAMLDS" discoveryURL="">
- Change the comment about the Urbana campus IDP to describe InCommon.
- Remove the URN of the entityID, but leave the quotation marks. The text will become:
- Add the InCommon discovery service between the quotes in discoveryURL. The text will become:
In the metadata section that says:
<!-- Configuration to consume I-Trust metadata. --> <MetadataProvider type="XML" url="https://discovery.itrust.illinois.edu/itrust-metadata/itrust-metadata.xml" backingFilePath="itrust-metadata.xml" reloadInterval="7200"> <MetadataFilter type="RequireValidUntil" maxValidityInterval="2419200"/> <MetadataFilter type="Signature" certificate="itrust.pem"/> <!-- Limit users to those from Urbana's IDP --> <MetadataFilter type="Whitelist"> <Include>urn:mace:incommon:uiuc.edu</Include> </MetadataFilter> </MetadataProvider>
- Change the comment to describe InCommon.
- In the MetadataProvider area, change the URI to "http://md.incommon.org/incommon-metadata/incommon-metadata.xml"
- In the MetadataFilter Signature area, change the certificate to "inc-md-cert.pem"
- Download http://md.incommon.org/certs/inc-md-cert.pem (external link) and verify the cert correctness using the instructions at https://spaces.internet2.edu/display/InCFederation/Metadata+Signing+Certificate (external link). Then save it in the same directory as the shibboleth2.xml and attribute-map.xml files.
- In the MetadataFilter Whitelist area, the default whitelist is
set to the Urbana campus IDP. This means that only members of the Urbana
campus could successfully connect with this configuration. You could
change this to allow additional IDPs in one of two ways:
- Add the entity ID of each organization's IDP that you want
to allow. Place each entity ID inside its own <include> and
</include> tags. (You can get entity ID information from the
InCommon metadata file or from the IDP administrators of the other
- Remove the whitelist filter entirely, which would allow members of any organization in the federation to connect. You can choose to restrict access elsewhere by using the eduPersonPrincipalName or organizationName attribute.
- Add the entity ID of each organization's IDP that you want to allow. Place each entity ID inside its own <include> and </include> tags. (You can get entity ID information from the InCommon metadata file or from the IDP administrators of the other permitted campuses.)
Access restrictions and sessionError.html
This copy of shibboleth2.xml can be configured to restrict access to specific IDPs, meaning that if someone tries to log in through a different IDP, the sessionError.html template will be returned to that person. You may want to customize that file to suit your site's look and feel.
The attributes with names that don't start with iTrust should be widely supported by InCommon IDPs. Therefore, you should use eduPerson attributes when possible to ensure the greatest compatibility with other universities' attribute naming conventions. Uncomment whichever eduPerson or other non-iTrust attributes your application needs.
The use of eduPersonPrincipalName is highly recommended for federated applications, while uid is not recommended. That's because two different people can have the same NetID or uid at two different institutions, but when you scope it (firstname.lastname@example.org) to the end of it, the identifier becomes unique.
Download the iTrust certificate
Download https://discovery.itrust.illinois.edu/itrust-certs/itrust.pem and place it in the same directory as shibboleth2.xml.
Federating with InCommon (Usual practice)
In order to complete federating with inCommon, the Shibboleth service managers will need to register you as a delegated administrator in the InCommon Federation Manager and help you enter your metadata. (This is easiest to do if you've already gotten things working in I-Trust first, as noted above.)
The Shibboleth managers will then need to approve your submission to InCommon as the campus site administrators.
After that, InCommon staff will review and approve the submission before publishing the metadata.
Once this is done, all InCommon IDPs will have their metadata within 24 hours.
Federating with Other Institutions (Rare practice)
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.
If you want to select a few universities to participate: Run a discovery serviceThe above discoveryUrl settings will send your user to the InCommon centralized discovery service which lists all institutions in InCommon when asking the user to select their campus. This is more than likely overkill for your needs unless you really are allowing logins from every school in InCommon. You can, of course, whitelist only the organizations whose users should be allowed in on your service provider, but all InCommon members will still be presented to your users from the discovery service.
In a case like this, you may wish to run your own embedded discovery service. This not only lets you choose which institutions are presented as options to your users, but it allows you to give the discovery service page the same look and feel as the rest of your site. Conveniently, embedded discovery services are extremely easy to set up and configure, and the Shibboleth project offers one. Installation and configuration instructions can be found at https://wiki.shibboleth.net/confluence/display/EDS10/Embedded+Discovery+Service
Next, continue from step 7 (restart and registration) in Shibboleth, Setting up a Service Provider .