For IT Pros This page contains information about the I-Trust Federation, an SAML-compliant service that allows users from each of the three University of Illinois campuses to gain access to secure applications using their own local identity credentials. This information is intended for campus IT Professionals. If you are an end-user, please contact your IT Professional with any questions that you may have about this service.
NOTE: This documentation assumes that you are a campus IT service administrator who wishes to learn more about establishing your service in the I-Trust Federation. It assumes that you already understand essential web server and web application concepts and terminology. This documentation will focus on an explanation of I-Trust itself rather than an explanation of web server or web application concepts.
The University of Illinois has established aamong the University's organizations and service providers called the I-Trust Federation. Its goal is to allow easy authentication and authorization to services regardless of who runs the service or what organization the user is coming from. Currently, all three of the University of Illinois campuses are established in I-Trust. Its service providers are the web-based applications that need to be used by one or more of these campuses.
Your service belongs in I-Trust if all of the following describe it:
These instructions assume that SiteMinder won't work for you and that you already have your service provider software installed. If you are looking for instructions on installing the Shibboleth Service Provider, see Shibboleth, What is it?. If you're using a different service provider or your SAML communications are built into your application, you should consult your vendor documentation.
You can add your service I-Trust using the I-Trust Federation Registry. The I-Trust Federation Registry is a web-based tool for adding and modifying information about a service in the federation. To access it and add a service provider:
Logging in allows your newly-created service provider to be associated with you for easy access and modifications.
Entering your service's URL & logo will enable them to be displayed by identity providers on login pages and inside of the federation registry.
You have now registered your service provider.
Your registration needs to make its way through an approval workflow to be approved by your campus's organizational contact and the federation administrator. This can take a couple of days, but will usually happen quickly. You can see the status of the approval process from the dashboard (the main screen of the federation registry). Once it's approved, you'll also receive an email.
To communicate with I-Trust, you'll need to make a few changes to your service provider. These are:
Metadata can be consumed from https://md.itrust.illinois.edu/itrust-metadata/itrust-metadata.xml.
You should always verify the validity of the metadata by both checking the Valid Until date in the metadata file and the signing of the metadata. Signature validity can be performed against the I-Trust certificate at https://md.itrust.illinois.edu/itrust-certs/itrust.pem. You'll need to download the certificate and place it on your server where your SP software can read it.
Software like the Shibboleth SP makes consuming and validating this metadata simple by adding a block like this to your shibboleth2.xml inside of the ApplicationDefaults section:
<MetadataProvider type="XML" uri="https://md.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" />
If you'll be allowing users from multiple I-Trust member organizations to use your service, you'll need a so they can select their home institution and be directed to the correct IDP. Alternatively, if you want to limit it to only one IDP and bypass the IDP selection process, you can directly configure this as well.
The easiest way to allow for IDP selection is to use the I-Trust centralized discovery service. You'll need to configure your service provider to redirect logins to the discovery service page at https://discovery.illinois.edu/discovery/DS. This will work with any software that supports the use of the SAML DS protocol. If you're running the Shibboleth SP, you can use the following SSO tag in your shibboleth2.xml:
If you want to only allow logins from a single organization and bypass the discovery service, simply give your service provider the entityID of the IDP to use. In Shibboleth's SP, it would look like this:
You may wish to use the centralized discovery service mentioned above but not let all I-Trust organizations in to your application. You can do this by whitelisting the IDPs you wish to give access to. This can be done by including a metadata filter, something supported by some SPs. If your service provider doesn't support this, you'll have to create a process to manually extract the IDPs you want from the I-Trust metadata.
If you're using the Shibboleth service provider, you only need to insert a block like this into your metadataProvider block of shibboleth2.xml. EntityIDs can be pulled from the entityDescriptor tags in the I-Trust metadata of the IDPs you want to allow.
The following would limit logins to users from the three University of Illinois campuses:
Receiving attributes from an IDP won't do your service provider any good if it's not properly decoding those attributes and mapping them to valid names. Every service provider should have a configuration file or process for doing this.
If you're using the Shibboleth Service Provider, it's in your attribute-map.xml. To locate this file, look for the path to it in shibboleth2.xml. The file that ships with the SP provides a number of standard attributes which you only need to uncomment to use.
Make sure you uncomment the SAML2 attributes, the ones with numeric OIDs in their definitions. If you've requested an attribute from the federation that isn't listed in this file, adding it is simple. You can copy it from any other line in the attribute map, changing its OID and name. The OID can be found in the Federation Registry.
View your service provider in the registry and click SAML then Attributes. The name can be whatever you want it to be, as long as it's the name that your application is expecting. For sanity, we recommend naming the attributes the same as what's listed in the Federation Registry web interface.
Once you've created your service provider's entry in the I-Trust Federation, you may wish to make some changes to it. The Federation Registry provides an easy interface to do this.
Most of the changes you'll probably need to make are in the SAML tab. A couple of common tasks:
Since most SPs will automatically construct the response endpoint using the hostname from the URL that a user uses to get to your site, it's necessary to have a set of endpoints for each protected virtual host on your server. Adding these takes a bit of manual work, but it's mostly copy and paste.
If your service provider's certificate is going to expire soon, we recommend replacing it. This is best done by adding the new certificate, waiting for the federation to consume it, then deleting the old one. For best results, this should be done a few days before the old certificate expires.