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.

Up: Contents Previous: 3. How do I install Shibboleth SP for IIS? Next: 5. How do I register my Service Provider?