Configure a Shibboleth SP to Use the InCommon Per-Entity Metadata Distribution Service

Last updated: November 1, 2024
Audience: IT Staff / Technical

This document describes how to configure a Shibboleth Service Provider (SP) to fetch metadata for specific InCommon IdPs only when needed. This method is referred to as a per-entity metadata service or MDQ (since it’s based on the “Metadata Query” protocol). To learn about other options to consume UW IdP metadata, see UW IdP Metadata.

Configuration

Configuration Steps

Shibboleth SP v3

  • Open your shibboleth2.xml file for editing.
  • Find the section with MetadataProvider elements.
  • Add the current MetadataProvider with the following:
MDQ SP v3
<!-- InCommon Per-Entity Metadata Distribution Service -->
<MetadataProvider type="MDQ" id="incommon" ignoreTransport="true" cacheDirectory="inc-mdq-cache"
maxCacheDuration="1440" minCacheDuration="60"
baseUrl="https://mdq.incommon.org/">
<MetadataFilter type="Signature" certificate="inc-md-cert-mdq.pem"/>
<MetadataFilter type="RequireValidUntil" maxValidityInterval="1209600"/>
</MetadataProvider>
  • It is recommend that you enable a metadata cache duration of at least one hour, but no longer than one day, in your Shibboleth SP.
  • The first MetadataFilter element requires that the signature on the MDQ metadata provider should be verified using the inc-md-cert-mdq.pem certificate.
  • If you have configured a MetadataProvider for the UW IdP or InCommon metadata aggregate, you should comment it out or delete it.
  • Save your shibboleth2.xml file.

Configuring with multiple metadata providers

If you have more than one metadata provider configured (for example, for IdPs that are not part of InCommon), you will want to put the InCommon Per-Entity Metadata Distribution Service after any other metadata providers. Otherwise, your SP will needlessly attempt to use MDQ to fetch IdP metadata from InCommon before falling back to the correct metadata provider.

  • Download the MDQ signing certificate.
  • Save the certificate file in the same directory as your shibboleth2.xml file. Name it "inc-md-cert-mdq.pem".

  • Restart the shibd process on your SP however you normally do that on your platform.
  • This will cause your SP to re-read the metadata provider configuration in shibboleth2.xml and to take appropriate actions.

  • The restart of shibd, building metadata providers, and loading certificates for signature verification should all be recorded in shibd.log.
  • Open the log file and scroll to near the bottom of the file to find messages from the shibd restart.
  • Look for messages like the following (numbering added for clarity, these are not present in the log file) to verify MDQ was configured on restart:
    1. 2019-12-27 11:32:16 INFO OpenSAML.MetadataProvider.Chaining : building MetadataProvider of type MDQ
    2. 2019-12-27 11:32:16 INFO OpenSAML.MetadataProvider : building MetadataFilter of type Signature
    3. 2019-12-27 11:32:16 INFO XMLTooling.SecurityHelper : loading certificate(s) from file (C:/opt/shibboleth-sp/etc/shibboleth/incommon-mdq.pem)
    4. 2019-12-27 11:32:16 INFO XMLTooling.CredentialResolver.File : no private key resolved, usable for verification/trust only
    5. 2019-12-27 11:32:17 INFO OpenSAML.MetadataProvider.Dynamic [incommon]: cleanup thread started...running every 1800 seconds