Deploying Shibboleth on a New Web Server

Owned by Paul Riddle
Last updated: Mar 31, 2020
5 min read

Here are the steps you'll need to follow to install and deploy a Shibboleth Service Provider (SP) on a web server at UMBC. The goal is to expedite this process for everyone involved, so the individual steps will likely evolve over time.

First, a quick note on terminology.

  • Security Assertion Markup Language (SAML) is the XML-based protocol that Shibboleth uses "under the hood".
  • Shibboleth is the software package that implements SAML. Very roughly speaking, Shibboleth is to SAML as Firefox/Chrome/Safari/IE is to HTML.

With that out of the way.. here is what you'll need to do.

  1. Install and enable Secure Sockets Layer (SSL) on the web server. Shibboleth will work without SSL, and by default, will encrypt SAML traffic that passes through the user's browser. However, it's highly advisable to use SSL/TLS on the web server as an additional layer of security. If you have any intention of ever using SSL on the web server, install it before configuring Shibboleth. It's easier to do it now than to go back and do it after Shibboleth is already set up and running. If you don't yet have a CA-signed certificate for the web server, you can set everything up using a self-signed certificate, and then switch the cert later. Shibboleth doesn't care about the web server's certificate; the only important thing is that the server needs to be listening and serving content over HTTPS.
  2. Make sure your web application does not intercept requests to https://yourserver.umbc.edu/Shibboleth.sso. The SP uses this path for session initiation and SAML traffic.
  3. Install the Shibboleth SP software. Supported platforms at UMBC are Redhat/CentOS Linux (RHEL6 and RHEL7) and Windows Server 2008/2012/2016.
    • Other platforms: You're free to use any platform that can run the SP software, but DoIT may not be able to help if you have problems with an unsupported platform.

  4. Install UMBC-specific configuration files. Download the following 6 files, and drop them in place of the default versions. For Linux, the files go in /etc/shibboleth; for Windows, they go in C:\opt\shibboleth-sp\etc\shibboleth:

    Make sure you get the correct version of shibboleth2.xml for your platform (Linux or Windows).

  5. Customize the shibboleth2.xml file.

    • First, you'll need to choose a SAML entity ID. The entity ID is a globally unique string that identifies your SP. By convention, we use URL-formatted strings because it's easy to make them globally unique; however, the entity ID is never used as an actual URL, so does not need to point to a valid web page. Unless you have a really good reason to use something else, use your web server's URL and add /shibboleth to the end. For example, if your web server is https://yourserver.umbc.edu, your entity ID should be https://yourserver.umbc.edu/shibboleth. Edit shibboleth2.xml, find the <ApplicationDefaults> element, and replace the default entity ID there with yours:

      <ApplicationDefaults entityID="https://yourserver.umbc.edu/shibboleth" ...

      Choosing a good entity ID

      Think of an entity ID as a "primary key" field in a global database of identity providers and service providers. IdPs use the entity ID to look up info about SPs, and vice versa. As such, the entity ID needs to be globally unique. Also, it's very important to understand that an entity ID refers to a service, not a server. If your service has a different user-facing hostname than that of the underlying server, or has multiple nodes behind a load balancer, the entity ID should be named based on the user-facing name of the service. An example here is worth 1000 words. Assuming your service is called "fido":

      Good entity ID: https://fido-prod.umbc.edu/shibboleth

      Bad entity ID: https://fido-prod2-v3.core.umbc.edu/shibboleth

      When named properly, the entity ID should stay the same regardless of what happens with the underlying server. If you're moving a service with an existing SP to a newer VM, just copy the entire Shibboleth configuration over (everything in the /etc/shibboleth directory) – no need to start again from scratch, or change the entity ID.

    • For Windows/IIS only, look for the <ISAPI> section. Within it, there should be a line that looks like:

      <Site id="1" name="myserver.umbc.edu"/>

      Make sure the site ID matches the site number in IIS. In most cases, it will be 1. If not, change this line so that the IDs match. Also, replace the site name with the canonical (user-facing) hostname of your web server.

    • For Windows/IIS only, in the <RequestMapper> section, look for <Host name="myserver.umbc.edu"> and replace the name with the canonical (user-facing) hostname of your web server. Similarly, in the <ISAPI> section, look for <Site id="1" name="myserver.umbc.edu"> and replace this hostname as well.

    • Next, decide what identifier you are going to use for users logging into your application. Most UMBC applications use either the myUMBC username, or the 7-character Campus ID. This identifier will be visible to your application in the REMOTE_USER environment variable (Apache) or HTTP_REMOTE_USER header (IIS). If you want to use myUMBC username, no further changes are needed. If you want to use campus ID, go to line 24 and replace 'umbcusername' with 'umbccampusid':

      REMOTE_USER="umbccampusid eppn persistent-id targeted-id">

  6. Restart the web server and the SP. For Linux/CentOS 6: service shibd restart; service httpd restart. For Linux/CentOS 7: systemctl restart shibd httpd. For Windows, restart the "Shibboleth Daemon (shibd)" service and IIS or Apache (whichever you are using). Make sure it comes back up cleanly. If not, check shibboleth2.xml for errors.

    The SP logs errors to /var/log/shibboleth/shibd.log (Linux) or \opt\shibboleth-sp\var\log\shibboleth\shibd.log (Windows). Any critical errors in shibboleth2.xml or other configuration files should show up in this file. Alternatively, from the command line, you can run /usr/sbin/shibd -t (Linux) or \opt\shibboleth-sp\sbin\shibd -check (Windows) to check the file for errors.

  7. Download your SP's metadata. From a web browser, go to https://yourserver.umbc.edu/Shibboleth.sso/Metadata. It should serve up an XML-format metadata file. If the web server will use SSL, make sure you use SSL (https://...) to download the metadata. Save this file for later. If this doesn't work, check your logs for errors (/var/log/shibboleth/shibd.log or C:\opt\shibboleth-sp\var\log\shibboleth\shibd.log). Also, per step 2 above, make sure your web application is not intercepting requests to /Shibboleth.sso.
  8. Decide what user attributes your application needs. Besides a user identifier like Campus ID or username, some applications need information like first name, last name, email address, campus affiliation, etc. The SP makes these available to applications via environment variables (Apache) or HTTP headers (IIS). The following set of commonly-used attributes will be released to all UMBC service providers by default. If you need something not on this list, include it in your request and we'll see what we can do. Keep in mind that all data is subject to FERPA restrictions, and DoIT reserves the right to reject requests for attribute release on a case by case basis.
    • email (email address)
    • surname (last name)
    • givenName (first name)
    • displayName (full name in a display-friendly format)
    • title (job title)
    • telephoneNumber (office phone)
    • employeeNumber (PeopleSoft emplid)
    • eduPersonAffiliation (student, faculty, staff etc)
    • umbccampusid
    • umbcusername
  9. Submit an RT ticket requesting setup for your SP. The ticket should go to the "DoIT-Identity Management" queue. Include the following things in the ticket.
    • The XML metadata file you downloaded in step 7. Include this as an attachment to the ticket.
    • The entity ID for your SP
    • The URL for your web server. If the web server will use SSL, make sure the URL starts with https://...
    • Any attributes you are requesting that are not included in the list shown in step 8
  10. That's it! Providing you include all requested items from step 9 in your ticket, your SP should be ready to go within 2 business days.

If you have any special requests not covered by the steps above, include them in your ticket, and we'll work with you to accommodate them.

Request Help | Correct or Suggest an Article