How to Set Up a Shibboleth 2.X Service Provider on Windows and IIS

This document is for U-M information technology staff members. It provides basic instructions on installing Shibboleth 2.X Service Provider (SP) software on Windows Server and Internet Information Service (IIS) 7.x and configuring it for the U-M 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. Ports 80 and 443 must be open to inbound traffic, and port 8443 must be open to outbound traffic.

  3. Install IIS and the IIS 6 Management Compatibility if using IIS 7 or above.

    • Install IIS 6 Management Compatibility by going to Administrative Tools > Server Manager > Roles > Web Server (IIS) > Role Services. The Shibboleth installer uses those management interfaces, and cannot function properly without it.

    • It is also recommended that you install ASP.NET so that test scripts can be run once the installation is up and running.

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

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

1. Verify Installation

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

  1. In Control Panel, open Administrative Tools > Services. The Shibboleth service (Shibboleth 2 Daemon) should have Service = Started, Startup Type = Automatic and Logon As = Local System as the settings.

  2. Open 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 for a 64-bit install.

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

  4. 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 = Inherited. If the *.sso entry mapping is missing, you will need to create it:

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

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

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

2. Set Up Federation Files and Metadata

Shibboleth Service Provider Resources has links to the InCommon Federation metadata and certificate, as well as the U-M metadata and certificate. These resources are essential for configuring your installation, so it is a good idea to have both that document and this one open at the same time.

  • Save the InCommon certificate to the following filepath:
    C:\opt\shibboleth-sp\etc\shibboleth\inc-md-cert.pem

  • Save the U-M certificate to the following filepath:
    C:\opt\shibboleth-sp\etc\shibbboleth\umwebCA.pem

Important Your SP should refresh the metadata for U-M and InCommon at least daily. Daily metadata refresh helps protect users of your SP from phishing and spoofing. See the InCommon Federation page on Metadata Consumption for more.

3. 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 the U-M Shibboleth Identity Provider (IdP). The file comes with the Shibboleth SP software, and is located by default at C:\opt\shibboleth-sp\etc\shibboleth.

Refer to a sample shibboleth2.xml file with U-M specific comments, or follow these instructions to make the appropriate changes to the file to configure it for your SP.

Note 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.umich.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 the host name, or a static identifier of your website. The entity ID does not need to resolve to a webpage.

    • In the SessionInitiator element within the ApplicationDefaults element, the entityID there should be updated to the U-M entityID. The entityIDs for the staging and production environments are different.

  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 Identity and Access Management team to communicate any changes made to the SP owners.

  5. Update the U-M metadata provider:

    • Update the MetadataProvider element (as there are several) by changing the uri value to the U-M metadata. The metadata address is different for staging and production, so be sure to update it to the appropriate value.

    • In the MetadataProvider element, update the MetadataFilter certificate value with the umwebCA.pem certificate.

  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.

    • Within the MetadataProvider element, locate the MetadataFilter certificate value, and update the certificate to inc-md-cert.pem.

  7. Specify authentication paths within your service if necessary:

    • If only some parts of the service will require Shibboleth or two-factor authentication, 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". This setting is required if your service will be protected by two-factor authentication. See Configuring Your U-M Shibboleth Service Provider for Two-Factor Authentication for more.

  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.umich.edu -e entityID -y number of years to issue

where the values for each are substituted accordingly (this example uses the U-M production entityID):

keygen.bat -h example.umich.edu -e https://shibboleth.umich.edu/idp/shibboleth -y 10

The 10 indicates the number of years for which the certificate is issued. You may specify a different value.

Modify attribute-map.xml

Your SP’s attribute-map.xml file decodes the attributes released by the U-M Identity Provider (IdP). For more about U-M attribute releases, see U-M InCommon Shibboleth Attribute Release Policy and Procedure . The default Shibboleth SP configuration will not recognize some of the U-M-specific attributes such as uniqname, so the attribute-map.xml file needs to be modified.

Refer to a sample attribute-map.xml file with U-M specific comments, or see below for relevant excerpts from the file.

  • The ePPN attribute is this section:

     
    <Attribute name="urn:mace:dir:attribute-def:eduPersonPrincipalName" id="eppn">
         <AttributeDecoder xsi:type="ScopedAttributeDecoder"/>
    </Attribute>
    <Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.6" id="eppn">
         <AttributeDecoder xsi:type="ScopedAttributeDecoder"/>
    </Attribute>

  • The affiliation attribute is this section:

     
    <Attribute name="urn:mace:dir:attribute-def:eduPersonScopedAffiliation" id="affiliation">
         <AttributeDecoder xsi:type="ScopedAttributeDecoder" caseSensitive="false"/>
    </Attribute>
    <Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.9" id="affiliation">
         <AttributeDecoder xsi:type="ScopedAttributeDecoder" caseSensitive="false"/>
    </Attribute>

  • The unscoped affiliation attribute is this section:

     
    <Attribute name="urn:mace:dir:attribute-def:eduPersonAffiliation" id="unscoped-affiliation">
         <AttributeDecoder xsi:type="StringAttributeDecoder" caseSensitive="false"/>
    </Attribute>
    <Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.1" id="unscoped-affiliation">
         <AttributeDecoder xsi:type="StringAttributeDecoder" caseSensitive="false"/>
    </Attribute>

  • The uniqname attribute is this section:

     
    <Attribute name="urn:mace:dir:attribute-def:uid" id="uid"/>
    <Attribute name="urn:oid:0.9.2342.19200300.100.1.1" id="uid"/>

4. Register Service Provider

Generate SP metadata

  1. Restart IIS and the Shibboleth 2 service. The Shibboleth 2 service can be restarted using the Control Panel > Administrative Tools > Services navigation.

  2. Navigate to https://example.umich.edu/Shibboleth.sso/Metadata, updating example.umich.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 the Shibboleth Configuration Request Form. The Identity and Access Management (IAM) team will contact you when you can begin testing.

5. Test Installation

Test SP configuration

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

Test SP integration with IdP

After the IAM team has contacted you and has added your metadata to the U-M staging IdP, you can test your SP to ensure it is properly integrated with the U-M 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 U-M staging 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.

6. Prepare for Production

After your SP passes testing:

  1. Update your shibboleth2.xml file with production values in place of staging values. Update the U-M entityID in the SessionInitiator element, and the metadata in the MetadataProvider element.

  2. Contact the IAM team to let them know that your configuration is ready for production.



 

Tags: 
Shibboleth
Last Updated: 
Wednesday, July 22, 2015 - 00:00