How to load NCSU Federation Metadata on an SP

Shibboleth Service Providers (SPs) should be setup to load our federation metadata directly from our website. This allows us to add new hosts, make key/certificate changes, and generally keep things in sync without having to ask each individual SP to update their files every time we need to make a change.

First, check to see how your SP is configured to load metadata. Check the /etc/shibboleth/shibboleth2.xml file for MetadataProvider tags like one of these examples:

<!-- This loads a static file. -->
<MetadataProvider type="XML" file="someidpfile.xml"/>

versus

<!-- This loads the federation files dynamically. -->
<MetadataProvider type="XML" 
    url="https://docs.shib.ncsu.edu/federation/metadata.xml" 
    backingFilePath="ncsu_fed_metadata.xml" reloadInterval="7200">
  <MetadataFilter type="Signature" certificate="ncsu_federation.pem"/>
</MetadataProvider>

If you are using static metadata files, you should reconfigure your SP to load our metadata dynamically.

Converting to dynamically loaded metadata

Make sure your server/firewall will allow the software to download a file from our metadata URL: https://docs.shib.ncsu.edu/federation/metadata.xml.

If a firewall prevents the server from downloading our file, there should be a way to setup the SP to use a proxy. See the Shibboleth documentation for NativeSPTransportOption.

Download our federation signing certificate and save it to your /etc/shibboleth directory.

cd /etc/shibboleth
wget https://docs.shib.ncsu.edu/federation/ncsu_federation.pem
chmod 644 ncsu_federation.pem

Next, edit your shibboleth2.xml file.

vi /etc/shibboleth/shibboleth2.xml

Remove (or comment out) the static MetadataProvider tag(s). Add in our dynamic MetadataProvider:

<!-- This loads the federation files dynamically. -->
<MetadataProvider type="XML" 
    url="https://docs.shib.ncsu.edu/federation/metadata.xml" 
    backingFilePath="ncsu_fed_metadata.xml" reloadInterval="7200">
  <MetadataFilter type="Signature" certificate="ncsu_federation.pem"/>
</MetadataProvider>

Note that if your SP belongs to multiple federations, you may need to chain together multiple MetadataProvider tags. See NativeSPMetadataProvider for more information.

Once you have made these changes, restart your shibd service and your httpd server:

service shibd restart
service httpd restart

Check your shibd logs to make sure the metadata is loading properly. In the server log you should find entries like this:

less /var/log/shibboleth/shibd.log
2014-05-05 10:38:13 INFO OpenSAML.MetadataProvider.XML : loaded XML resource (https://docs.shib.ncsu.edu/federation/metadata.xml)
2014-05-05 10:38:13 INFO OpenSAML.Metadata : applying metadata filter (Signature)
2014-05-05 10:38:13 INFO OpenSAML.MetadataProvider.XML : adjusted reload interval to 7200 seconds

If this did not work, review the Wrong libcurl bug section below. You can also verify that the backing file was created with the downloaded metadata:

ls -l /var/cache/shibboleth/
-rw-r--r-- 1 shibd shibd 592958 May  5 10:38 ncsu_fed_metadata.xml

Next you should test one or more of your protected applications, to make sure the IdP and SP are still working together correctly.

For more information on how to configure MetadataProviders, please see the Shibboleth documentation on NativeSPMetadataProvider.

Wrong libcurl bug

If you have upgraded an older SP from 2.4 to 2.5 on a RHEL6 machine, you may run into a problem with finding the correct libcurl-openssl when shibd tries to start. As a result, the shibd process may throw an error when it tries to dynamically download our federation metadata. The error that we see in the log is:

less /var/log/shibboleth/shibd.log
2014-05-06 08:54:31 ERROR XMLTooling.libcurl.InputStream : \
  error while fetching https://docs.shib.ncsu.edu/federation/metadata.xml: \
  (59) Unknown cipher in list: ALL:!aNULL:!LOW:!EXPORT:!SSLv2
2014-05-06 08:54:31 ERROR XMLTooling.libcurl.InputStream : \
  on Red Hat 6+, make sure libcurl used is built with OpenSSL

You should have the correct libcurl installed, but it is set to install in a non-standard path. To verify the install and the library path, run:

rpm -ql libcurl-openssl
/opt/shibboleth
/opt/shibboleth/lib64
/opt/shibboleth/lib64/libcurl.so.4
/opt/shibboleth/lib64/libcurl.so.4.3.0

To resolve this problem, you need to make sure your shibd init script preloads that libcurl path in LD_LIBRARY_PATH. Here's one way to fix it:

vi /etc/init.d/shibd
  # parse down the file to the line:
  shibd="/usr/sbin/shibd"
  # add this line just after it:
  export LD_LIBRARY_PATH=/opt/shibboleth/lib64:$LD_LIBRARY_PATH

Now when you reload shibd with "service shibd restart" it should use the correct libcurl, should no longer throw that error, and it should load the remote metadata as expected.

Common questions

Does the backingFilePath name matter?

No, it does not. This file is used exclusively by the shibd software to store a local copy of the metadata. It will be written to the private cache directory, normally /var/cache/shibboleth. You may use any name that you like. If you have multiple federation feeds, they should each have unique names, of course.

What does this error mean: No MetadataProvider available?

Your shibd process was unable to read any of your MetadataProvider information. Check:

Are there comment tags around your MetadataProvider entry? The default config file has many examples that are left commented out. You may have edited one of those and forgotten to remove the comment tags.
Make sure your tag is configured correctly. Refer to your /var/log/shibboleth/shibd.log file to see if there were errors during loading.

Can we selectively load the metadata?

This question was posed by the MyPack portal. They run their own Discovery Service, and it automatically suggests each of the IdPs that it finds in the metadata. They only wanted to use our two production IdPs in their list.

The shibd software has a number of MetadataFilter options. One of them is already used to check the Federation signature on the whole file. Others can be added to selectively keep or remove entities by name or attributes. This example shows how to load our metadata and filter out everything except our two production IdPs.

<MetadataProvider type="XML"
      url="https://docs.shib.ncsu.edu/federation/metadata.xml"
      backingFilePath="ncsu_fed_metadata.xml"
      reloadInterval="7200">
    <MetadataFilter type="Signature" certificate="ncsu_federation.pem"/>
    <MetadataFilter type="Whitelist">
        <Include>https://shib.ncsu.edu/idp/shibboleth</Include>
        <Include>https://shib.ncsu.edu/other-idp/shibboleth</Include>
    </MetadataFilter>
</MetadataProvider>

However, this filter does not appear to apply to the metadata as it is used by their Discovery Service. They found it better to download the individual IdP metadata files from our website instead. This example shows how to load our two production IdPs directly, without using the signed Federation metadata.

<MetadataProvider type="Chaining">
  <MetadataProvider type="XML"
        url="https://docs.shib.ncsu.edu/federation/metadata-shib-idp-ncsufed.xml"
        backingFilePath="ncsu_idp_metadata.xml"
        reloadInterval="43200" />
  <MetadataProvider type="XML"
        url="https://docs.shib.ncsu.edu/federation/metadata-shib-other-idp.xml"
        backingFilePath="ncsu_other_idp_metadata.xml"
        reloadInterval="43200" />
</MetadataProvider>

If you use this code, keep in mind that the individual IdP files are not signed. You are trusting that the files you get from our URL are the correct ones. This is probably safe for an on-campus service, where it is unlikely we will have a DNS poisoning or other network attack.