Shibboleth, Establishing Your Service in the I-Trust Federation

What is I-Trust?

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:

• You are running SAML-compliant software such as the Shibboleth project's Service Provider 
• You need to allow users from one or more campuses who are part of the federation
• Your service is in the cloud (or for other reasons can't use SiteMinder)

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.

How to add your service to I-Trust 

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:

1. Open itrust.illinois.edu (external link) and click Welcome - Please Login.
2. The I-Trust Discovery Service page may appear. If it does, select your campus and click Select this campus.
3. A Shibboleth login screen should then appear. Enter your username & password and click Login.
   

   Logging in allows your newly-created service provider to be associated with you for easy access and modifications.

4. This opens the I-Trust Federation Registry Dashboard. Under My Service Providers, click View All.
5. This opens the Service Providers / List page. Click the Create tab.
6. This opens the Create Service Providerpage. Fill it out as follows:
   1. STEP 1: Primary Contact
      Make sure that your name and email are correct.
   2. STEP 2: Service Provider Description
      • Organization: Select your campus.
      • Display Name:  Enter the display name of your service. This can be the name of the application/service or, if more appropriate, the hostname of its server. This name will be displayed on discovery service and identity provider login pages when a user is logging in.
      • Description: Enter a brief (a few words) description of your service for other federation members. This name will be displayed on discovery service and identity provider login pages when a user is logging in.
      • Service URL: Enter the URL to your service.
      • Service Logo URL: (Optional) Enter the URL to your service's logo.
        

        Entering your service's URL & logo will enable them to be displayed by identity providers on login pages and inside of the federation registry.

   3. STEP 3: SAML Configuration
      • Easy registration using defaults: Use this option if you are using the Shibboleth project's service provider. Just select your SP version (usually 2.4 or 2.5) and enter the URL to your service (typically of the form "https://hostname.domain.illinois.edu"). The rest will be filled in automatically.
      • Advanced SAML 2 registration: Use this option if you are using another service provider. You will need to enter your SAML endpoints one-by-one in each field. Consult your vendor documentation for your endpoint URLs.
   4. STEP 4: Public Key Certificate
      Copy and paste your service provider's signing and encryption certificate here.
      
      NOTE:
      

      • This usually isn'tthe same certificate that is used by your web server:
        • If you're using the Shibboleth SP, this certificate is in the file configured with the certificate attribute in the CredentialResolver block of shibboleth2.xml. By default, it's /etc/shibboleth/sp-cert.pem.
      • The form will automatically check to ensure that your certificate is valid.
      • Self-signed certificates are allowed for this purpose.
   5. STEP 5: Requested Attributes
   6. This step is important: it's how you configure what information the IDP sends to your SP after a user logs in. Some of this information may be for display purposes in your application such as a user's name, but the critical part is authorization. You should never assume, just because a user successfully authenticated to the IDP, that they're authorized to use your service.  
       
      • First, determine what you need to know about a user to decide if they should be granted access.
      • Then, request the attributes you need to make that decision and configure your application appropriately.
      • In the web interface, select the attributes your service needs by checking each applicable Requested checkbox.
      • Enter an explanation of why each attribute is needed in Reason for requesting (e.g., "this attribute is needed to identify staff and faculty in order to grant access"). Please be specific.
      • If the service must have the given attribute in order to grant access to your users, also check the Required checkbox.
        
        
   7. STEP 6: Service provider ready to be registered
      Click Submit if all of the previous steps are complete and you are ready to register your service.

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.

Configuring your service provider to work with I-Trust

To communicate with I-Trust, you'll need to make a few changes to your service provider. These are:

Consume I-Trust metadata

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" />

</MetadataProvider>

Optional: Use the I-Trust Discovery Service

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.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:

<SSO entityID=""
 discoveryProtocol="SAMLDS" discoveryURL="https://discovery.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="">

Allowing access to a subset of IDPs in I-Trust

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>

Mapping attributes

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.

Changing your service provider in I-Trust

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.

1. Log in to the I-Trust Federation Registry Dashboard. (external link)
2. Under My Service Providers, click View All.
3. Under Functioning, click the View button for your service provider.
4. The Service Provider - itrust.illinois.edupage will open. Seven tabs are available:
   • Overview: Basic info about your service that you entered during registration.
   • Categories: Information about what type of service your service provider is.
   • Contacts: People who should be listed in the metadata if someone needs to contact staff related to your service. It's important that you keep this up-to-date.
   • SAML: The communications endpoints and attributes configured for your service.
   • Reporting: Data about how your service provider is being used.
   • Monitoring: Checks that the Federation Registry can perform to ensure your service provider is up and running. This is not intended to take the place of enterprise solutions already in place and should be used only as secondary.
   • Administrators: Federation Registry users who can modify your service provider’s Federation Registry entry. It's a good idea to have more than one.

Most of the changes you'll probably need to make are in the SAML tab. A couple of common tasks:

Request a new attribute:

1. From the Service Provider - itrust.illinois.edu page, click the SAML tab.
2. Under the SAML tab, click the Attributes tab.
   • To remove an attribute you no longer need, click the Remove button next to that attribute.
   • To request a new attribute, click Add and enter the same information you submitted with your original attribute requests.

Add a new virtualhost to your SP:

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.

1. From the Service Provider - itrust.illinois.edu page, click the SAML tab
2. Under the SAML tab, click the Endpoints tab.
   Five tabs will appear, one for each type of endpoint:
   • Assertion
   • Artifact
   • Logout
   • Discovery
   • Name ID.
3. The Assertion tab is selected by default.
4. Using the endpoints already listed in this section as your examples, create new endpoints using the same binding type.
5. Using the same location URL, replace the hostname from the existing endpoint with that of your new virtual host.
6. Repeat these steps for each of the other tabs as needed.

Replace an expiring certificate:

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.

1. Before adding your new certificate to the Federation Registry, add it to your SP as the first certificate to be used with a Use Constraint of Encryption Only. If you're using the Shibboleth SP, a blank Use Constraint means both signing and encryption, which should be what's currently listed for your old certificate.
2. Now, log into the Federation Registry. (external link) From the service provider page, click the SAML tab.
3. Under the SAML tab, click the Certificates tab.
4. When you see your certificates and their expiration dates:
   1. STEP 1: Click Add to add your new certificate.
   2. STEP 2: Enter a name in the Name field. NOTE: The name field is cosmetic and purely for your own information.
   3. STEP 3: Paste your certificate into the Certificate window.
   4. STEP 4: Leave both Signing and Encryption checked unless you have a reason not to do so.
5. Wait a couple of days to ensure that all IDPs have updated metadata with your new certificate. This will normally take four hours or less, but unusual circumstances or an IDP configured much differently from the defaults can cause this time to vary (it requires the IDPs' local copies of the federation metadata to expire so they can obtain new copies).
6. Once things have had time to propagate, change your SP configuration to use the new certificate for both signing and encryption while using the old certificate for encryption only. Remember: With the Shibboleth SP, a blank Use Constraint means both signing and encryption.
7. If nothing breaks at this point (i.e. if you can still log in to your service), delete the old certificate from the Certificates tab of the Federation Registry.
8. Again, wait a couple of days for metadata to propagate, then remove the old certificate from your SP configuration.