SP Metadata

We're working on improving Raven resources for developers and site operators.

Try out the new Raven documentation for size.

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.

For SPs registered with the UCam federation, a copy of their metadata is stored within the Raven IdP - a copy of the Ucam federation metadata file can be accessed at https://shib.raven.cam.ac.uk/ucamfederation-sp-metadata.xml. For SPs in the UK federation their metadata is included in the UK federation metadata file.

SPs metadata normally associates three things:

• The SP's 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 auto-generated metadata is not intended to address every eventuality. It's an XML file and there is nothing to stop you from editing it after generation (assuming you know what you are doing) or even creating it by other means.

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 security (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>, <HostRegex>, <Path>, <PathRegex> or <Query> element to the https port number within the shibboleth2.xml <RequestMapper> element. Note that you can't add this property to the <RequestMapper> itself - adding it doesn't casue an error but it doesn't work either. 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 when 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" or "No peer endpoint available to which to send SAML response" and to refuse to process the request. Despite the message being reported by the IdP, it reflects a problem on the SP.