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 a trust federation among 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://discovery.itrust.illinois.edu/itrust-metadata/itrust-metadata.xml. (external link)
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://discovery.itrust.illinois.edu/itrust-certs/itrust.pem. (external link) 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://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" />
</MetadataProvider>
If youâll be allowing users from multiple I-Trust member organizations to use your service, youâll need a Discovery service
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.itrust.illinois.edu/discovery/DS. (external link)
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:
<SSO entityID=""
discoveryProtocol="SAMLDS" discoveryURL="https://discovery.itrust.illinois.edu/discovery/DS">
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:
<SSO entityID="urn:mace:incommon:uiuc.edu"
discoveryProtocol="SAMLDS" discoveryURL="">
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.
<MetadataFilter type="Whitelist">
<Include>
https://idp.goodguy.com/shibboleth
</Include>
<Include>
https://idp.betterguy.com/shibboleth
</Include>
</MetadataFilter>
The following would limit logins to users from the three University of Illinois campuses:
<MetadataFilter type="Whitelist">
<Include>
urn:mace:incommon:uiuc.edu
</Include>
<Include>
https://shibboleth.uic.edu/shibboleth
</Include>
<Include>
https://uisshibb1.uis.edu/idp/shibboleth
</Include>
</MetadataFilter>
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.