Single Sign On: Install and Configure Shibboleth SP on Windows and IIS

The aim of this document is to assist FAU information technology staff members with setting up Single Sign On (SSO) access for approved sites. It provides basic instructions on installing the most recent version of Shibboleth's Service Provider (SP) software on a Windows Server using Internet Information Services (IIS) 8.5 (but can be used on IIS 7 and above) and configuring it for the FAU Identity Provider (IdP).

Basic familiarity with Windows Server and IIS systems administration is assumed. Configuring the software requires the ability to read and edit XML files with a text editor.

Server Preparation

1. Acquire a server.
2. Open firewall ports, if necessary. Port 443 must be open to inbound traffic.
3. Download the latest version of the Windows installer package from the Shibboleth Project site, selecting the appropriate install file directory for your system. A 32-bit system will require the win32/ directory and the 64-bit system the win64/ directory. You will need to download the .msi file.

Install Shibboleth

1. Run the appropriate installer, accepting the default settings. When the installer is complete, it will prompt you to restart the machine.

   1. The plugin modules in support of IIS are always installed. If IIS itself is installed you will be prompted "Configure IIS7 module?".  Check this box to actually configure Shibboleth to run with IIS, in practice this can be done with two command.

      No need for 32-bit shibd on 64-bit OS

      The 32-bit web server modules can function with a 64-bit shibd service, so there is no need to install a special version of shibd to handle 32-bit cases as with older SP versions.

      Startup Failures

      If you experience startup problems, you should do the following:

      • Verify the configuration is generally valid by running %SHIBSP_PREFIX%/sbin/shibd.exe -check from the command line.
      • 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).
      • Assuming that reports no serious errors, verify that all of the machine accounts used by IIS have read permission to the SP installation tree.

Verify Installation

If the Shibboleth SP installation was successful, your Windows server should display the following settings in IIS:

1. Visit Control Panel > System and Security > Administrative Tools > Services. The Shibboleth service - Shibboleth Daemon (Default) - should have Status = Running, Startup Type = Automatic and Log On As = Local System as the settings.
   
    
2. Open Internet Information Services (IIS) Manager and verify that the Shibboleth ISAPI filter is installed.
   • Click the server name and open ISAPI Filters.
     
      

   • The settings should be Name = Shibboleth and Executable = C:\opt\shibboleth-sp\lib64\shibboleth\isapi_shib.dll and Entry Type = Local for a 64-bit install.

     If it does not exist, select Add... from the upper right hand corner in Actions and add the name and executable then click Save

3. 1. Still in IIS Manager, verify that the Shibboleth ISAPI filter is mapped to the .sso extension.
      • Click the server name and open Handler Mappings.
        
         
      • The settings should be Path =*.sso, State = Enabled, Path Type = Unspecified, Handler = IsapiModule, Entry Type = Local.
   2. Still in IIS Manager, verify that the handler mapping inheritance properly cascaded down to the website level.
      • Click the website name under Sites, then open Handler Mappings. The settings should be Path =*.sso, State = Enabled, Path Type = Unspecified, Handler = IsapiModule, and Entry Type = Local (or Inherited).
        
         
      • If the *.sso entry mapping is missing, you will need to create it:

        • If you don’t have any local mappings configured, click “Revert to Parent” in the Action pane. This will copy all mappings from the server level down to the website level, deleting any local mappings at the website level.

        • If you do have local mappings configured, you can manually create the mapping in the Action pane by clicking Add Script Map and filling in the dialog box to match the server, with Request path = *.sso and Executable = C:\opt\shibboleth-sp\lib64\shibboleth\isapi_shib.dll for a 64-bit install. The Name field can be anything you like, but we recommend using Shibboleth.

   3. Update access control list
      • In File Explorer, navigate to C:\opt\shibboleth-sp\etc\shibboleth right-click on shibboleth2.xml and select Edit
        
        
         
      • Be sure to add the server's IP address to the Status reporting service section's acl tag
   4. In a web browser on the server, go to the case-sensitive URL https://localhost/Shibboleth.sso/Status, but do not substitute your server’s full domain name in place of /localhost/. If everything is properly configured, it should return an XML document with <Status><OK/></Status> at the bottom.

Configuration

Configure shibboleth2.xml file

The shibboleth2.xml file will need to be configured for your Service Provider (SP) to allow it to work with FAU's Identity Provider (IdP). The file comes with the Shibboleth SP software, and is located by default at C:\opt\shibboleth-sp\etc\shibboleth.

Follow these instructions to make the appropriate changes to the file to configure it for your SP.

Before making changes, save a copy of the original shibboleth2.xml file

1. Update the site ID and name:
   • In the ISAPI element, verify that the Site id=”1” value refers to the correct site ID number for the website that will be Shibboleth enabled. 1 is the ID number for the default web site as assigned by IIS. Clicking Sites in IIS will reveal the ID assigned to this site.
   • Update name=”sp.example.org” to the host name of your website, for example name=”https://example.fau.edu”
2. Update the host name:
   • In the RequestMapper element, update the Host name=”sp.example.org” field to the host name of your website.
3. Update the entityID:

   • In the ApplicationDefaults element, the entityID value should be updated from entityID=”sp.example.org” to a static identifier of your website. The entity ID does not need to resolve to a webpage.

     The entityID should not contain the name of the server or any ID codes, we prefer that vanity names and URLs be used or your request will be denied.

   • In the Sessions element within the ApplicationDefaults element, update the cookieProps to https and handlerSSL to true.

   • In the SessionInitiator element within the ApplicationDefaults element, the entityID there should be updated to the FAU entityID. The entityIDs for the test and production environments are different.

     The entityID for Test is: https://ssot.fau.edu/idp/shibboleth

     The entityID for Prod is: https://sso.fau.edu/idp/shibboleth

     You must set your SP to resolve with Test first. It must be tested and approved by our SSO Integration team prior to being allowed to resolve against Prod.

4. Update the support contact:
   • In the Errors element, update the supportContact value to a valid email address for the person managing the SP configuration. This email address is used by the SSO Integration team to communicate any changes made to the SP owners.
5. Update the FAU metadata provider:
   • Update the MetadataProvider element (as there are several) by changing the url value to the FAU metadata (https://metadata.fau.edu/rr3/metadata/federation/FAU-EDU/metadata.xml).
   • In the MetadataProvider element, update the MetadataFilter certificate value with the umwebCA.pem certificate.
   • Comment out the MetadataProvider type="Signature" line
   • Uncomment the MetadataProvider element.
6. Update the Federation metadata provider:

   • If your SP will also be available to a federation such as InCommon, update a second MetadataProvider element by changing the uri value to the InCommon federation metadata.

     The URL to use is: https://metadata.fau.edu/rr3/metadata/federation/FAU-EDU/metadata.xml

7. Specify authentication paths within your service if necessary:
   • If only some parts of the service will require Shibboleth, use Path tags within the RequestMapper element to create a path to the parts of the service that will be Shibboleth-enabled.
   • If the entire service will require Shibboleth authentication, use the RequestMapper element. In the Host name section, set an authType="shibboleth" and set requireSession="true".
8. Save shibboleth2.xml.

Install an X509 certificate

As Shibboleth requires a certificate and key to encrypt and decrypt attribute assertions, an X509 certificate must be installed for it to work. Now that the shibboleth2.xml file has been updated, use the keygen.bat command in C:\opt\shibboleth-sp\etc\shibboleth to create new certificates with the correct hostname and entityID. Use the following format:

keygen.bat -h example.fau.edu -e entityID -y number of years to issue

 

where the values for each are substituted accordingly (the first example uses the FAU test entityID and the second uses the production entityID):

#TEST keygen.bat -h example.fau.edu -e https://ssot.fau.edu/idp/shibboleth -y 50     #PROD keygen.bat -h example.fau.edu -e https://sso.fau.edu/idp/shibboleth -y 50

The 50 indicates the number of years for which the certificate is issued. You may specify a different value, but it is your responsibility to keep track of when the certificates expire. If they are not replaced prior to expiration, your service will cease to work until a new certificate is uploaded.

Modify attribute-map.xml

Your SP’s attribute-map.xml file decodes the attributes released by the FAU Identity Provider (IdP). The default Shibboleth SP configuration will not recognize some of the FAU-specific attributes so the attribute-map.xml file may need to be modified. Please submit a ticket to our SSO Integration team for further information if you need assistance with an attribute.

Register Service Provider

Generate SP metadata

1. Restart IIS and the Shibboleth Daemon service. The Shibboleth Daemon service can be restarted using the Control Panel > Administrative Tools > Services navigation.
2. Navigate to https://example.fau.edu/Shibboleth.sso/Metadata, updating example.fau.edu to your entity ID.
3. Verify that your entity ID has replaced the example entity ID in the metadata file. If it has not, make sure that all instances of it have been updated in shibboleth2.xml.
4. If your entity ID is correct throughout the metadata, download the SP metadata.

Contact Identity and Access Management team

Once you have your SP metadata, submit an SSO request ticket. The SSO Integration team will contact you when you can begin testing.

Test Installation

Test SP configuration

Visit SAMLtest.id to set up and test your SP configuration to make sure that it works as expected.

Test SP integration with IdP

After the SSO Integration team has contacted you and has added your metadata to the FAU IdP, you can test your SP to ensure it is properly integrated with the FAU IdP. Confirm that you are able to log in with your account or a test account, and that attributes are properly released.

1. Place this attribute release test script in the /secure directory of your SP, or the protected location you set using the RequestMapper element in the shibboleth2.xml configuration file.
2. Using a web browser, visit the /secure directory (or other protected location) of your SP. You should be prompted to log in, and after logging in, you should see the attributes associated with the account that you used to log in to the secure directory.
3. If you are prompted to log in, that means that your SP is properly integrated with the FAU IdP.
4. If the appropriate attributes are displayed, that means that attributes are being released successfully to your SP and that the attribute-map.xml file is properly configured.

Configure for Production

After your SP passes testing:

1. Update your shibboleth2.xml file with production values in place of test values. Update the FAU entityID in the SessionInitiator element, and the metadata in the MetadataProvider element.
2. Contact the SSO Integration team to let them know that your configuration is ready for production.

 

 

This document has been adapted from the University of Michigan: https://documentation.its.umich.edu/node/354 and Shibboleth: https://wiki.shibboleth.net/confluence/display/SP3/Install+on+Windows