Install Shibboleth Service Provider 3.x on Windows and IIS


 
Shibboleth Service Provider 3.2.2 is the current version. No previous versions are supported by the Shibboleth Consortium.
  This document describes the procedure used to install Shibboleth Service Provider (SP) software on Windows Server and Internet Information Server (IIS), and to configure it to work with the UW Identity Provider (IdP). The instructions support a basic install for a single web site and application, authenticating users with their UW NetID. More advanced configuration topics will be covered separately.

Prerequisites

The reader should have prior Windows Server and IIS system administration experience. The ability to read and edit XML files with a text editor is required to configure the software. The IIS website must have an appropriate x509 certificate installed and SSL enabled.  Shibboleth Service Provider 3.x software supports Windows Server 2008 and later, and installers are available for both 32-bit and 64-bit systems.  Shibboleth 3.x supports the versions of the IIS web server that are provided with the supported Windows versions. For upgrades from version 2.x, a legacy ISAPI module is provided for compatibility but will be discontinued in a future version, and the new IIS native module should be used instead.  (See note at the bottom of this page)

Configuration Steps

Configuration Steps

  1. Download the latest version of the Windows installer package from the Shibboleth download site at https://shibboleth.net/downloads/service-provider/latest/. Select either the win32/ or win64/ directory as appropriate to your 32-bit or 64-bit system. These instructions were tested as follows:
    • Service Provider 3.0.3
      • Windows Server 2016 and IIS 7.5
  2. Run the installer package. It is recommended that you accept all defaults, as follows:
    • Accept the license agreement
    • Install to C:\opt\shibboleth-sp
    • Configure IIS7 module is checked
    • Click Next, then Install, then Finish
    • Click Yes to restart your system
  1. On the Administrative Tools menu, click Services. Find Shibboleth 2 Daemon in the list and double-click it.  Verify that Service Status is Running, Startup type is Automatic, and on the Log On tab, verify that Local System is selected.
  2. Verify the configuration is generally valid by running the code below from the command line: 
    %SHIBSP_PREFIX%/sbin/shibd.exe -check
    If the last line of the output is the following message, everything is as expected: 
    overall configuration is loadable, check console for non-fatal problems
    If there are any ERROR messages, we strongly recommended you resolve them. Messages with log level WARN are generally not problematic but should be noted and re-investigated after configuration steps are complete. If you experience startup problems, you should do the following:
    • Make sure the system path contains the location of the SP's library DLLs (and make sure you reboot after installation before assuming that's happened).
    • Verify that all of the machine accounts used by IIS have read permission to the SP installation tree.
    • Check the logs in C:/opt/shibboleth-sp/var/log/shibboleth. The "shibd" log file will record shibd service start up messages and errors.
  1. Depending on the needs and capabilities of your Service Provider, you have multiple IdP metadata configuration options. UW IdP Metadata describes the options and makes recommendations based on use case. It provides links to the following:
Save a copy of C:\opt\shibboleth-sp\etc\shibboleth\shibboleth2.xml to shibboleth2.xml.orig or similar then open shibboleth2.xml in a text editor. Type carefully; one of the biggest sources of problems is typos made in this file.
  1. Find <ISAPI...>...<Site id="1" name="sp.example.org"/>.
    • Change the site id to match the id assigned to your site by IIS. The site id will be 1 for the default web site. You can find your site id in Internet Services (IIS) Manager by clicking on "Sites".
    • In this same location, change the name to your DNS name (e.g. myserver.mydept.washington.edu). Go ahead and put your DNS name in your paste buffer because you'll need to enter it twice more.
    • Verify that scheme="https" and port="443".  Note that if you're using a non-standard SSL port you should use that instead of 443.
  2. Find <RequestMap>...<Host name="sp.example.org">.
    • Change the name to your DNS name.
  3. Find <ApplicationDefaults entityID=" https://sp.example.org/shibboleth "...>.
  4. Find <ApplicationDefaults...>...<Sessions...>...handlerSSL="false" cookieProps="http"> ...
    • Change to handlerSSL="true" cookieProps="https">
  5. Find <ApplicationDefaults...>...<Sessions...>...<SSO entityID="https://idp.example.org/shibboleth"...>
  6. Find  < Errors supportContact ="root@localhost"  helpLocation ="/about.html" styleSheet ="/shibboleth-sp/main.css"  />
    • Change the email address to your application's support email address.
  7. Find the <MetadataProvider...>...</MetadataProvider> section and un-comment the metadata type you'll be using by removing the <!-- and --> tags that surround it.
  8. If your SP will rely only on the UW IdP for user authentication, skip steps 9 and 10 and follow instructions at UW IdP Metadata. If your SP will rely on other IdPs from InCommon, continue on at step 9.
  9. If your Service Provider will be configured to accept users from other (non-UW) InCommon IdPs, follow the instructions at Configure a Shibboleth SP to Use the InCommon Per-Entity Metadata Distribution Service to add the MDQ metadata.
  10. Save shibboleth2.xml and close your editor.
  11. Use Internet Services (IIS) Manager to restart IIS and Administrative Tools > Services to restart the Shibboleth 2 Daemon.
  12. Restart the web server and the access the URL from the server's browser:   https://<your dns name>/Shibboleth.sso/Session .   The web server should return a page that says: 
    A valid session was not found.
    This message demonstrates that the Shibboleth module is loaded by the webserver and is communicating with the shibd  process.
  13. Download your SP metadata from https://<your dns name>/Shibboleth.sso/Metadata.
    • Depending on your OS and browser, the metadata might be displayed in the browser or you might be asked to save the file. If you save the file with a .xml file extension and open the file in your browser it will be easier to read.
    • Make sure there are no instances of sp.example.org in the URLs; any such references should have been replaced by your DNS name.  The file will contain a warning about reviewing the contents of the file and not supplying it in real time-that's normal.
    • Checking for sp.example.org counts as review, and our registry doesn't monitor the contents of that file after the initial registration (i.e. not real time).
  1. You must register your SP in the UW SP Registry at https://iam-tools.u.washington.edu/spreg. See Register a Service Provider with the UW for instructions.
  2. It will take a few minutes for your registration to propagate to the UW IdP before you can begin testing. See Flow of Metadata and Filter Policies from SP Registry to the IdP for the current schedule.
At this point you should have a basic installation of Shibboleth that works with IIS. There are a few quick tests you can do to verify this. Note that there are potentially many more configuration changes you will need to make to integrate Shibboleth with your application and get it ready for production use. Those topics are outside the scope of this document and will be covered elsewhere.
  1. As configured, Shibboleth will not yet be protecting your web site. To verify this, use your browser to request a document from the root of your web site. The document should be returned without being redirected through the UW IdP for authentication.
  2. By default, Shibboleth is configured to protect content in a directory named /secure in the root of your web site. Most likely that directory doesn't exist. To do a quick test that Shibboleth is working as expected, create /secure in the root of your web site (not in the IIS install root directory) and add a sample document. When you request that document with your browser you should be redirected through the UW IdP to the UW NetID sign-in page. Sign in with your UW NetID and the sample document should be returned to you.
  3. While still signed in, open a new tab and point your web browser to https://<your dns name>/Shibboleth.sso/Session and review the response.  Your browser should return a status page similar to this: 
    Miscellaneous
Session Expiration (barring inactivity): 479 minute(s)
Client Address: 205.175.119.11
SSO Protocol: urn:oasis:names:tc:SAML:2.0:protocol
Identity Provider: urn:mace:incommon:washington.edu
Authentication Time: 2018-11-15T19:16:09.514Z
Authentication Context Class: urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
Authentication Context Decl: (none)

Attributes
affiliation: 3 value(s)
eppn: 1 value(s)
Refer to the documents on the Shibboleth Service Provider Support page for help with the rest of your Service Provider configuration. Be sure to subscribe to the Shibboleth Project's announcement list. This is a low traffic list used to announce new releases and security advisories.
 

See Also:

Shibboleth Project's Service Provider 3  reference. Note: Existing 2.x installations configured to work with IIS will continue to do so, but require the older ISAPI plugin to be updated. See this topic for details, particularly about migrating to the newer plugin.