1. What is 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. You can read more about Shibboleth on the Internet2 Shibboleth pages.

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

2. What are the system prerequisites?

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.

2.1. Role Services Preparation

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.

Add Role Services Screen

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.

3. How do I install Shibboleth SP for IIS?

First download the appropriate 32-bit or 64-bit .msi Shibboleth SP installer from the Internet2 downloads site.

Double-click the MSI file that you downloaded, and the installer will show the following dialogue:

Installer Welcome Screen

Click Next and the following dialogue box will be shown:

License Confirmation Screen

Select I accept the license agreement and click Next to see an Information screen.

Installation Information Screen

Read the text if you are not familiar with what the installer will be doing, and click Next to show the Destination Folder screen.

Destination Folder Screen

It is recommended that you accept the default destination folder. Click Next to show the Shibd Service screen.

Set Up Service Screen

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.

Set Up ISAPI Filter Screen

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.

Ready For Installation Screen

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

Installation In Progress Screen

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

Installation Complete Screen

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

Restart Dialogue Box

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.

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

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

4. How do I configure the Shibboleth SP software after installation?

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:

4.1. The <InProcess> element

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"/>

4.2. The <RequestMapper> element

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.

4.3. The <ApplicationDefaults> element

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.

4.4. The <Sessions> element

This can be found within the <ApplicationDefaults> element. 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.

4.4.1. Federated Access

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

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

4.4.2. Oxford-Only Access

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

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

4.5. The <Errors> element

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

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

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

4.6. The <MetadataProvider> element

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" uri="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).

4.7.

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

Shibboleth Service Restart

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.

5. How do I register my Service Provider?

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 'Metadata', for example).

In line with the UK Federation registration guidelines, attach the Metadata file to an email containing the information listed in the UK Federation SP registration pages, and send it to Oxford's Shibboleth management liaison who will verify the information provided and then submit an SP registration request on your behalf to the UK Federation.

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 either the Script Method to run a script to display the certificate fingerprint using familiar Windows dialogues, or follow the Extension Renaming Method so the Windows OS recognises the file as a certificate.

5.1. Script Method

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

5.2. Extension Renaming Method

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.

6. What next?

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 a request should be sent to shibboleth@oucs.ox.ac.uk 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).