Installing Shibboleth SP for IIS

We recommend Shibboleth Service Provider (SP) software for setting up Single Sign-On (SSO) for web applications. The Shibboleth SP software for IIS is maintained by Internet2, and comprises an ISAPI filter, an ISAPI extension, and a local daemon process.

Although the Shibboleth SP installer takes care of much of the set-up and configuration, some customisation of the configuration is necessary to establish the required links to the UK Federation. This guide assumes some familiarity with Windows Server administration, and is aimed at setting up a basic Shibboleth SP configuration that will seamlessly wrap the Oxford Username authentication pages. This guide was written for IIS 7.x with both 32-bit and 64-bit Windows Server 2008 (and 2008 R2). The Shibboleth developers, Internet2, state that the Shibboleth SP software will also work for IIS 6.x with Windows Server 2003, although that configuration is beyond the scope of this guide. The SP configuration sections of this guide apply to Shibboleth SP v2.4.x, but installations should use the latest version available.

Expand All

There are 3 basic prerequisites:

  • Either 32-bit or 64-bit Windows Server 2008 (or 2008 R2) should be installed, with the Application Server role activated/installed. All applicable and up-to-date security patches should be applied.
  • The Shibboleth daemon should be capable of receiving Assertion Consumer Service traffic over SSL, so the IIS website you will be integrating with Shibboleth should be set up with a valid SSL certificate. Instructions for obtaining and setting up IIS with an SSL certificate are documented here.
  • Before installing the Shibboleth SP software you should ensure that IIS has certain role services installed. These additional role services are required to enable the installer to properly configure your SP installation with IIS. See the Role Services Preparation section for more information about installing the required role services.

As an administrative user, open the Server Manager program, open 'Roles' in its left-hand pane, and click on Web Server (IIS). Scroll down to the 'Role Services' section and click on Add Role Services.

In the 'Application Development' section, ensure ISAPI Extensions and ISAPI Filters are checked, then further down the list ensure that IIS 6 Management Compatibility and all the checkboxes under it are checked.

Click Next, confirm that the changes are ok, and then click Install. When the results show that the installation succeeded, click Close to dismiss the dialogue box.

  1. 1. First download the appropriate 32-bit or 64-bit .msi Shibboleth SP installer from the Internet2 downloads site.
  2. Double-click the MSI file that you downloaded, and the installer will appear.
  3. Click Next
  4. Select I accept the license agreement and click Next to see an Information screen.
  5. Read the text if you are not familiar with what the installer will be doing, and click Next to show the Destination Folder screen
  6. It is recommended that you accept the default destination folder. Click Next to show the Shibd Service screen.
  7. Ensure that the Install Shibd daemon is checked. The default port 1600 should be fine, unless you already run another service on this port in which case you should choose an alternative unused port. Click Next to show the Install ISAPI Filter screen.
  8. Ensure that Install ISAPI filter and configure IIS is checked. Keep the default '.sso' file extension for mapping to the ISAPI handler, and click Next to show the Ready screen.

  9. The installer should be now ready for installation. Click Next to install and configure the SP software.

  10. The installer will go through various stages of installation and configuration.

  11. Eventually the installer will indicate that installation has completed successfully. Click Finish.

  12. A dialogue box will appear indicating that you need to restart your system. Close any other open programs and click Yes to restart the server as directed.

  13. A successful installation will have applied a default configuration to the software. To summarise, the installer will have caused the following to happen:

 

  1. Addition of the Shibboleth ISAPI filter (ISAPI Filters)

  2. Mapping of the .sso file handler to the ISAPI library (Handler Mappings)
  3. Addition of the Shibboleth ISAPI Extension to the list of permitted extensions (ISAPI and CGI Restrictions)
  4. Installation and configuration of the shibd service
  5. Generation of a local self-signed X.509 certificate with corresponding key, to be used for signatures
  6. A system restart

 

When the machine has restarted, download the latest 'ukfederation.pem' certificate, copy it into C:\opt\shibboleth-sp\etc\shibboleth(substitute your installation location if you chose a non-default location), and rename it to 'ukfederation.crt' (this will cause Windows to recognise the file as a certificate by an extension that it recognises). This digital certificate will be used to verify UK Federation digital signatures. You should verify the certificate fingerprint by right-clicking on the ukfederation.crt file in Windows Explorer and selecting 'Open'. When the Certificate dialogue box opens, click on the 'Details' tab and scroll down to the 'Thumbprint' entry. This fingerprint value must be confirmed offline with the UK Federation Helpdesk to ensure its validity and guard against the possibility of your web site being compromised.

The installation uses the Shibboleth configuration file C:\opt\shibboleth-sp\etc\shibboleth\shibboleth2.xml, and the default Shibboleth configuration in this file needs some manual changes to align the Service Provider with the UK Federation. For our example changes to the configuration, a fictitious Service Provider name, shibbox.unit.ox.ac.uk, has been used. Edit the XML file as follows:

IIS divides a Web Host into Sites, each of which has a Site ID. The ID for your site can be found by clicking on the 'Web Sites' folder in IIS Manager and looking at the 'Identifier' column of the web site. Within the <InProcess> element, the <ISAPI> element must contain a <Site>element that matches the site ID and hostname of your SP. You should also include scheme="https" and port="443" to ensure the redirects are created correctly. For example, site 1 of shibbox.unit.ox.ac.uk would be configured as follows:

<Site id="1" name="shibbox.unit.ox.ac.uk" scheme="https" port="443"/>

Within the <RequestMapper> element, the <RequestMap> element contains a <Host> element that should be changed:

<Host name="sp.example.org">
  <Path name="secure" authType="shibboleth" requireSession="true"/>
</Host>

"sp.example.org" should be changed to the name of your new service provider, "shibbox.unit.ox.ac.uk" in this case. Note that the Path 'name' attribute is a mapping to the folder containing files that are to be protected by Shibboleth.

Change the entityId attribute of the <ApplicationDefaults> element to the "Entity ID" value of your SP:

<ApplicationDefaults entityId="https://sp.example.org/shibboleth" REMOTE_USER="eppn persistent-id targeted-id">
<!-- NOTE: Content omitted here for simplicity: do NOT remove contained elements -->
</ApplicationDefaults>

For this example substituting "sp.example.org" with "shibbox.unit.ox.ac.uk" will suffice.

 

This can be found within the <ApplicationDefaults> element, and should be changed to the following:

<Sessions lifetime="28800" timeout="3600" relayState="ss:mem" checkAddress="false" handlerSSL="true" cookieProps="https" redirectLimit="exact">

If you want to authenticate people from the wider UK Federation, follow the Federated Access Section, otherwise to authenticate people directly using Oxford Webauth, follow the Oxford-Only Access Section.

 

Replace the existing <SSO> element with the following <SSO> element:

<SSO discoveryProtocol="SAMLDS" discoveryURL="https://wayf.ukfederation.org.uk/DS"> SAML2 SAML1 </SSO>

 

Replace the existing <SSO> element with the following <SSO> element:

<SSO entityID="https://registry.shibboleth.ox.ac.uk/idp" discoveryProtocol="SAMLDS" discoveryURL="https://wayf.ukfederation.org.uk/DS"> SAML2 SAML1 </SSO>

For the supportContact attribute of the <Errors> element, provide a suitable contact email address:

supportContact="itsupport@unit.ox.ac.uk"

 

Please note:

Be aware that this email address may appear in error pages generated by your Service Provider.

 

 

Following installation the configuration is not set up to download remotely supplied metadata by default, so you must include a <MetadataProvider> element as follows:

insert the following block (altering /opt/shibboleth-sp if you installed in a non-default location so that it specifies your Shibboleth installation directory instead):

<MetadataProvider

    type="XML"
    url="http://metadata.ukfederation.org.uk/ukfederation-metadata.xml"
    backingFilePath="C:/opt/shibboleth-sp/ukfederation-metadata.xml"
    reloadInterval="14400">
  <MetadataFilter type="RequireValidUntil" maxValidityInterval="2592000"/>
  <MetadataFilter type="Signature" certificate="ukfederation.crt"/>
</MetadataProvider>

This will have the effect of refreshing your copy of the federation metadata every 4 hours (14400 seconds). As a security measure, it also causes metadata to be rejected whose root element does not specify a validUntil attribute, or whose validity period exceeds 30 days (2592000 seconds).

If this is a brand new service provider, you will need to generate trust fabric certificates with the correct entityID and host name.  The host names need not match, but both must be present in public DNS.

To generate the new certificates, run the following command with administrative privileges:

C:\opt\shibboleth-sp\etc\shibboleth\keygen.bat -h shibbox.unit.ox.ac.uk -e https://shibbox.unit.ox.ac.uk/shibboleth -f -n sp-encrypt
C:\opt\shibboleth-sp\etc\shibboleth\keygen.bat -h shibbox.unit.ox.ac.uk -e https://shibbox.unit.ox.ac.uk/shibboleth -f -n sp-signing

To pick up the above configuration changes, restart the shibd service then restart IIS.

Once the services have been restarted, open up the Shibboleth log file C:\opt\shibboleth-sp\var\log\shibboleth\shibd.log and confirm that there are no error or warning entries.

On your Windows Server machine, point your browser at http://localhost/Shibboleth.sso/Metadata (that URL will work for the default web site - the 'http://localhost' portion may vary for your configuration, it represents the root of your webapp) and save the metadata response in a file (called '<Hostname>.Metadata', for example).

To register the Service Provider, please complete the Registration of SAML Service Provider HEAT Service Request.

Verification of the information you have provided to the Shibboleth Management liaison will include verification of the SP signing certificate's fingerprint. The default path to the file containing the certificate is C:\opt\shibboleth-sp\etc\shibboleth\sp-cert.pem. Windows does not recognise the 'pem' file extension so to extract the fingerprint from the certificate you have two options, both of which will have the same effect. Follow one of the following methods to display the certificate fingerprint:

  1. The Script Method to run a script to display the certificate fingerprint using familiar Windows dialogues
  2. The Extension Renaming Method so the Windows OS recognises the file as a certificate
  3. The OpenSSL Method so the Windows OS recognises the file as a certificate

Remember to let us know which of the three methods you are using so that we know what form of fingerprint to expect.

Download a Windows PowerShell Fingerprint script and run it with PowerShell to select the SP signing certificate and display the fingerprint using familiar Windows dialogues, regardless of whether the extension is 'pem' or 'crt'.

Copy the SP signing certificate to a new filename first ('sp-cert - Copy.pem') and then change its extension from '.pem' to '.crt' so that Windows recognises the file as a certificate. You can then right-click the '.crt' file in Windows Explorer and select 'Open'. When the Certificate dialogue box opens click on the 'Details' tab, scroll down to the 'Thumbprint' entry and select it. Once you have verified the fingerprint with the UK Federation you can delete the 'sp-cert - Copy.crt' file.

he Shibboleth SP software comes with a copy of OpenSSL which keygen.bat uses to generate the trust fabric certificate (sp-cert.pem).  This can be used to obtain the certificate fingerprint.  Open a command prompt and run the following:

%ProgramFiles%\Shibboleth\SP\lib\openssl.exe x509 -in c:\opt\shibboleth-sp\etc\shibboleth\sp-cert.pem -text -noout -fingerprint -sha256

The last line will contain the SHA256 fingerprint.  Please remember to mention the fingerprint type when verifying the fingerprint to confirm that the right fingerprint type is being checked.

 

Now that your Service Provider is registered, your web application is all set to interpret the attributes placed in the HTTP Request Headers by Shibboleth to make the authorisation-related decisions that make sense for your web application. Attributes are made available by Shibboleth in the form of HTTP Headers. Shibboleth is capable of making further attributes available that originate from the Oak LDAP Service, so if your application needs more person-related attributes to make the required authorisation decisions please complete the SAML SP Attribute Release HEAT Service Request detailing the attributes required. You should ensure that the additional requested attributes have appropriate mappings configured in the Shibboleth SP attribute configuration file at C:\opt\shibboleth-sp\etc\shibboleth\attribute-map.xml when you are notified that the extra attributes have been released (substitute your installation location if you chose a custom installation location).

Access to the location can be restricted to individuals or groups using the RequestMap mechanism.

(https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPRequestMap and 

https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPXMLAccessControl).

<Host name="shibbox.unit.ox.ac.uk">
  <Path name="secure" authType="shibboleth" requireSession="true">
    <AccessControl>
      <RuleRegex require="affiliation">^.+@ox.ac.uk</RuleRegex>
    </AccessControl>
  </Path>
</Host>

 

<Host name="shibbox.unit.ox.ac.uk">
  <Path name="secure" authType="shibboleth" requireSession="true">
    <AccessControl>
      <Rule require="user">unit1234@ox.ac.uk</Rule>
    </AccessControl>
  </Path>
</Host>
<Host name="shibbox.unit.ox.ac.uk">
  <Path name="secure" authType="shibboleth" requireSession="true">
    <AccessControl>
      <AND>
        <RuleRegex require="affiliation">^.+@ox.ac.uk</RuleRegex>
        <Rule require="orgunit-dn">oakUnitCode=itserv,ou=units,dc=oak,dc=ox,dc=ac,dc=uk</Rule>
      </AND>
    </AccessControl>
  </Path>
</Host>

Note: This requires that the following lines are uncommented in c:\opt\shibboleth-sp\etc\shibboleth\attribute-map.xml:

    <Attribute name="urn:mace:dir:attribute-def:eduPersonPrimaryOrgUnitDN" id="primary-orgunit-dn"/>
    <Attribute name="urn:mace:dir:attribute-def:eduPersonOrgUnitDN" id="orgunit-dn"/>
    <Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.8" id="primary-orgunit-dn"/>
    <Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.4" id="orgunit-dn"/>

 

Get support


Local IT support provide your first line of on-the-spot help

FIND MY LOCAL IT TEAM

 

Common requests and fault reports can be logged using self-service

   USE IT SELF-SERVICE    

   LOG A SUPPORT CALL    

VIEW MY SUPPORT CALLS  

The central Service Desk is available 24x7 on +44 1865 6 12345

 

If you do not have an SSO account you can use this form to contact the Service Desk