Skip to content

Add a New Metadata Provider to Shibboleth

Overview

This guide explains how to add a new federation's metadata to our Shibboleth Service Provider. This is needed when we want our SP to trust Identity Providers from an additional federation — for example, adding CARSI (the Chinese academic federation) alongside our existing DFN, eduGAIN, UK Federation, ACOnet, and OpenAthens metadata sources.

Adding a metadata provider does not replace any existing federation trust. It adds a new source of trusted IdPs alongside the ones already configured.

Prerequisites

What You Need from the Federation

Before you start, gather the following from the federation you're adding:

  1. Metadata feed URL — the URL where the federation publishes its metadata XML. Example (CARSI): https://www.carsi.edu.cn/carsimetadata/carsifed-metadata.xml
  2. Metadata signing certificate — the certificate used to sign the metadata feed. This is typically embedded in the <ds:Signature> block at the top of the metadata XML itself, or provided separately by the federation.
  3. Discovery Service URL (optional) — only needed if the federation requires a separate login entry point. In most cases, existing IdPs will appear through the eduGAIN WAYF and no DS change is required.

Steps

1. Extract and Save the Metadata Signing Certificate

The signing certificate verifies the authenticity of the metadata feed. It is usually found inside the <ds:Signature> → <ds:KeyInfo> → <ds:X509Certificate> block at the very top of the metadata XML (not the individual entity certificates further down).

Extract the certificate content and save it as a PEM file in the configuration repository:

etc/shibboleth/<federation>-metadata-signing.pem

The file should look like:

-----BEGIN CERTIFICATE-----
MIIGKTCCBBGgAwIBAgIUEACe...
...
-----END CERTIFICATE-----

You can verify the certificate with:

openssl x509 -in etc/shibboleth/<federation>-metadata-signing.pem -noout -subject -issuer -dates

Example (CARSI): The signing certificate is issued by Peking University (CN=www.carsi.edu.cn), valid until 2049. It was saved as etc/shibboleth/carsi-metadata-signing.pem.

2. Add the MetadataProvider to shibboleth2.xml

Edit etc/shibboleth/shibboleth2.xml and add a new <MetadataProvider> block inside the existing <MetadataProvider type="Chaining"> section, alongside the other federation entries.

The general pattern is:

<MetadataProvider type="XML"
   url="<metadata-feed-url>"
   backingFilePath="/etc/shibboleth/<federation>-metadata.xml" reloadInterval="3600">
   <MetadataFilter type="Signature" certificate="/etc/shibboleth/<federation>-metadata-signing.pem"/>
   <MetadataFilter type="EntityRole">
      <RetainedRole>md:IDPSSODescriptor</RetainedRole>
   </MetadataFilter>
</MetadataProvider>

Where:

  • url — the federation's metadata feed URL
  • backingFilePath — local cache file, used when the remote URL is temporarily unavailable
  • reloadInterval — how often (in seconds) to re-fetch the metadata (3600 = hourly)
  • MetadataFilter type="Signature" — validates the metadata signature using the certificate from step 1
  • MetadataFilter type="EntityRole" with RetainedRole of md:IDPSSODescriptor — ensures only IdP metadata is loaded (we are an SP, we only need to know about IdPs)

Example (CARSI):

<MetadataProvider type="XML"
   url="https://www.carsi.edu.cn/carsimetadata/carsifed-metadata.xml"
   backingFilePath="/etc/shibboleth/carsi-metadata.xml" reloadInterval="3600">
   <MetadataFilter type="Signature" certificate="/etc/shibboleth/carsi-metadata-signing.pem"/>
   <MetadataFilter type="EntityRole">
      <RetainedRole>md:IDPSSODescriptor</RetainedRole>
   </MetadataFilter>
</MetadataProvider>

3. Deploy and Restart

  1. Commit and push your changes:

    git add .
git commit -m "Add <federation> metadata provider"
git push

  2. Deploy to both servers:

    ./deploy.sh
# Select option 3 (Both servers)

  3. Restart shibd on one instance at a time to maintain availability:

    ssh user@ec2-3-67-78-187.eu-central-1.compute.amazonaws.com 'sudo systemctl stop shibd && sudo systemctl start shibd'

  4. Wait for startup to complete (~90 minutes due to metadata parsing — see certificate renewal guide for details on why).

  5. Verify the service is healthy:

    curl https://shibboleth.statista.com/Shibboleth.sso/Status -k

  6. Then restart the second instance:

    ssh user@ec2-52-57-79-135.eu-central-1.compute.amazonaws.com 'sudo systemctl stop shibd && sudo systemctl start shibd'

⚠️ Warning: Adding a new metadata feed increases the total metadata volume that shibd needs to parse on startup. The CARSI metadata, for instance, is ~13 MB. This may slightly increase the already long startup time.

Verification

After both instances are running, verify the new federation's IdPs are recognized by testing a login flow from an institution in the new federation. For general Shibboleth login testing, see Test Shibboleth Login.

Check the logs for any metadata loading errors:

ssh user@hostname 'sudo grep -i "carsi\|metadata" /var/log/shibboleth/shibd.log | tail -20'

Notes

  • The Discovery Service URL does not need to change in most cases. IdPs from the new federation that are also part of eduGAIN will already appear in the DFN eduGAIN WAYF.
  • If the federation provides a separate Discovery Service and a dedicated login button is needed, that would require a change to the <SSO> block in shibboleth2.xml — but this is uncommon.
  • Remember to update the Shibboleth Server reference if the new metadata file should be documented there.
Last updated: March 24, 2026 at 10:39
By: Axel Tetzlaff