SP Metadata

Introduction

Shibboleth IdPs and SPs can publish 'Metadata' about themselves in XML (SAML v1.1, SAML v2). Typically SPs need access to the metadata describing the IdPs that they work with, and vice versa. Some IdPs (including Raven's) will provide services to SPs even if they don't hold any metadata for them - ironically for such IdPs, having incorrect metadata is normally worse than having no metadata at all.

For SPs registered in the UCam federation, a copy of their metadata is stored within the Raven IdP; for SPs in the UK federation their metadata is included in the UK federation metadata file.

SPs metadata normally associates three things:

• The SPs EntityID
• The URLs of services offered by the SP (in particular the "Assertion Consumer Service" (ACS) URLs to which IdPs can post assertions)
• Certificate(s) describing the cryptographic keys used by the SP

The information in the metadata must match the SP's configuration and may have to be updated after configuration changes. This can be a problem since copies of the metadata are stored elsewhere and so should be avoided wherever possible. A mismatch between metadata and configuration will generally cause things to fail in strange ways, often with unhelpful error messages.

Creating Metadata

The normal configuration of the Internet SP sets up an automatic metadata generator which will generate metadata matching the configuration. You can access it it at:

http://<host-name>/Shibboleth.sso/Metadata

or, if your site supports https:

https://<host-name>/Shibboleth.sso/Metadata

The scheme (http vs. https) of the ACS URLs in the generated metadata will match that of the URL used to generate it. That's fine for a http-only website, but for one that supports both http and https this can cause problems when someone accesses the site using a different scheme from that used in the metadata.

The full explanation appears below, but the problem can be avoided in several ways:

• Force all access to the site to be over https. This is probably the best solution since it also provides better secutity (see SSL, certificates and security with Shibboleth). This can either be done within the web server or the site it is serving, or by the SP using either the ShibRedirectToSSL Apache directive (ShibRedirectToSSL <portnumber>) or by setting the 'redirectToSSL' attribute of a <RequestMap>, <Host>, or <Path> element to the https port number within the shibboleth2.xml <RequestMapper> element. The https port number is commonly 443.
• Set the 'handlerSSL' attribute of the <Sessions> element to "true". This will force all ACS URLs (and other internally-serviced URLs) to use the https scheme but will continue to allow the content of the site to be accessed over http. (Re-)generate the metadata using the https scheme.
• Register both http and https URLs in the SP metadata. This can be most easily achieved by adding https="true" http="true" attributes to the <Handler type="MetadataGenerator"> entry in shibboleth2.xml and then re-generating the Metadata.
• Disable http support completely.
• Disable https support and re-register your SP using just http: ACS URLs.

The full story

SP Metadata includes a list of the ACS URLs (in one or more <md:AssertionConsumerService> elements) to which IdPs are allowed to return information. When an SP makes an authentication request it includes (typically in the 'shire' parameter) the ACS URL to which it wants the results returned on this occasion.

SPs create ACS URLs from information in the shibboleth2.xml file (the 'handlerURL' and 'handlerSSL' attributes of the <Sessions> element and the 'Location' attribute of the relevant <AssertionConsumerService> element), and from the details of the virtual host handling the current request. In the default configuration, the SP uses the scheme (http: or https:) and host name of the virtual host and the values of the 'handlerURL' and 'Location' attributes to construct an ACS URL. In the default configuration, an authentication request using the SAML 1.0 Browser/POST profile triggered by access to

 http://www.example.cam.ac.uk/secure/

would include this as an ACS URL:

 http://www.example.cam.ac.uk/Shibboleth.sso/SAML/POST

A problem occurs when accessing an SP over http whan it also supports https and has registered https assertion consumer service URLs in it's metadata. In this case the ACS URL generated will be for http and these won't match those in the metadata. This causes the IdP to report "Invalid assertion consumer service URL" and to refuse to process the request. Despite the message being reported by the IdP, it reflects a problem on the SP.