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 the international Shibboleth Consortium, and comprises an IIS native module 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 originally written for IIS 7.x with both 32-bit and 64-bit Windows Server 2008 (and 2008 R2), but has been updated to work with more recent versions of Windows Server and IIS. The SP configuration sections of this guide apply to Shibboleth SP v3.x and later, but installers should use the latest Shibboleth SP version available.

Expand All

There are 2 basic prerequisites:

  • A fully supported 64-bit Windows Server version should be installed, with the Application Server role activated/installed. All applicable and up-to-date security patches should be applied. To maximise the period spent within Microsoft support for your service, you may wish to deploy to more recently released versions of Windows Server such as 2019 or 2022. This will avoid the need for more frequent server rebuilds, and will ensure you still receive security, stability and feature patches.

  • 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.
  1. First download the 64-bit .msi Shibboleth SP installer from the Shibboleth 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 proceed to the 'Configure Shibboleth' screen
  5. Read the text if you are not familiar with what the installer will be doing. It is recommended that you accept the default destination folder. Ensure the 'Configure IIS support' checkbox is ticked. Click 'Next'
  6. Click 'Install'
  7. The installer will go through various stages of installation and configuration
  8. Eventually the installer will indicate that installation has completed successfully. Click Finish
  9. 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
  10. 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 IIS 7+ native module

  • 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

 

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, see the Federated Access Section, otherwise to authenticate people directly using Oxford Single Sign-On, follow the Oxford-Only Access Section.

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>

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

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

 

 

You will need to include a <MetadataProvider> element to download remotely supplied metadata (from the UK Federation). Do this by adding the following configuration block:

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

Important Notes

Remember to set backingFilePath to the required location if you installed to a non-default location.

The default Shibboleth2.xml file has this block of code already in it, but you will need to remove the comment tags to activate it.

 

 

 

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 in IT self service.

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 signing certificate is C:\opt\shibboleth-sp\etc\shibboleth\sp-signing-cert.pem whereas the default path to the file containing the encryption certificate is C:\opt\shibboleth-sp\etc\shibboleth\sp-encrypt-cert.pem (NOTE: earlier versions of the Shibboleth SP software used a single file for both signing and encryption, C:\opt\shibboleth-sp\etc\shibboleth\sp-cert.pem). Windows does not recognise the 'pem' file extension so to extract the fingerprints from the certificates 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 OpenSSL Method so the Windows OS recognises the file as a certificate
  2. The Script Method to run a script to display the certificate fingerprint using familiar Windows dialogues

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

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

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

and (b) to produce the fingerprint for the encryption certificate:

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

In each case 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.

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

#----------------------------------------------------------------------------
# Fingerprint.ps1
#
# Convenience utility script to prompt the user to select a certificate, whose
# fingerprint will then be extracted and displayed in a MessageBox.
#
# Any selected files that are not x509 certificates (and so do not have a
# fingerprint) will be indicated as such in the resulting MessageBox
#----------------------------------------------------------------------------

# load up the essential windowing components
[System.Reflection.Assembly]::LoadWithPartialName("System.Windows.Forms") | Out-Null

# function to show a generic information message box
function Show-InformationBox {
    param([string]$title, [string]$message)
    [System.Windows.Forms.MessageBox]::Show(
        $message, 
        $title, 
        [System.Windows.Forms.MessageBoxButtons]::OK, 
        [System.Windows.Forms.MessageBoxIcon]::Information, 
        [System.Windows.Forms.MessageBoxDefaultButton]::Button1, 
        [System.Windows.Forms.MessageBoxOptions]::DefaultDesktopOnly
    ) | Out-Null
}

# function to show the file selection dialog box
function Select-FileDialog {
    param([string]$title="Select File",[string]$dir="C:\",[string]$filter="All Files (*.*)|*.*")
    $objSelect = New-Object System.Windows.Forms.OpenFileDialog
    $objSelect.Title = $title
    $objSelect.InitialDirectory = $dir
    $objSelect.Filter = $filter
    $objSelect.ShowHelp = $true
    $objSelect.CheckFileExists = $true
    $result = $objSelect.ShowDialog()
    if ($result -eq "OK") {
        return $objSelect.FileName
    }
}

# get the path to the file
$filepath = Select-FileDialog "Select a Certificate File" `
    "C:\opt\shibboleth-sp\etc\shibboleth" "Certificates (*.crt,*.pem)|*.crt;*.pem"
# do nothing if the dialog box was cancelled (ie $filepath is null)
if ($filepath) {
    # import the file as a certificate, trap an exception in case it isn't one
    $x509 = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2
    try
    {
        $x509.import($filepath)
        # prettify the fingerprint hex string and display it
        $certdata = $x509.GetRawCertData()
        $sha256alg = [System.Security.Cryptography.SHA256]::Create()
        $hash = $sha256alg.ComputeHash($certdata)
        $sha256alg.Dispose()

        $sha256 = [string]::Join(" ", $hash.ForEach{$_.ToString("X2")})
        $message = [string]::Format("SHA-256 fingerprint:`n{0}", $sha256)
        Show-InformationBox "Certificate Fingerprint" $message
    }
    catch
    {
        $message = "No fingerprint can be derived from " + $filepath
        Show-InformationBox "Not a Certificate" $message
        break
    }
    finally
    {
        if ($sha256alg -ne $null)
        {
            $sha256alg.Dispose()
        }
        if ($x509 -ne $null)
        {
            $x509.Dispose()
        }
    }
}

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: Extra Attributes 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.

(see RequestMap and XMLAccessControl documentation for more information)

<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


If you cannot find the solution you need here then we have other ways to get IT support

Get IT support