Retrieving Federation Metadata Updates Securely

After you have joined the Testbed Federation at either Level 1, 2 or 3, it is necessary to regularly download the latest metadata from the Testbed Federation website. This is due to the fact that the metadata is updated each time a member leaves or joins the Testbed Federation as an IdP or SP, and your Shibboleth installation needs to be aware of this information.

Since the metadata forms the basis of trust between members within each level of the Testbed Federation, it is necessary to prevent the metadata information from being forged and propagated by a malicious party. For that reason, the following steps have been taken to protect the integrity of the metadata:

• The metadata is distributed over HTTPS channel (currently only works with IdP tool).
• The metadata is signed by the Testbed Federation certificate. The signature can be checked using the metadatatool (shipped with Shibboleth IdP) and siterefresh tools (shipped with Shibboleth SP) when they download the latest metadata.

Below are the guides for configuring the IdP or SP to download the latest metadata securely.

For Shibboleth IdP

Shibboleth IdP is shipped with the metadatatool located in $IDP_HOME/bin directory. $IDP_HOME refers to the installation directory of Shibboleth IdP. The metadatatool can be used to download and verify the metadata signature against a given certificate. The steps for a configuring a Shibboleth IdP to receive new metadata on a hourly basis on a Debian system are:

• Prerequisites - You have successfully installed Shibboleth IdP.
• Download and import AddTrust External CA Root certificate to your Java default keystore. The default keystore is located in $JAVA_HOME/jre/lib/security/cacerts where JAVA_HOME is the location of your system Java JDK installation.
• Issue the following command to import it

  • $$JAVA_HOME/bin/keytool -import -alias AddTrustExternalCARoot -file AddTrustUTNServerCA.crt -keystore $JAVA_HOME/jre/lib/security/cacerts

• The default SUN JDK keystore password is changeit.
• Download the keystore containing the federation webserver certificate and the CA certifcate (AddTrust UTN Server CA) and place it the same directory as your script below. Note the password for the keystore is "testfed".
• Create a script called idp-metadata with the following content and place it in /etc/cron.hourly directory

    #!/bin/bash

    export METADATA_URL=https://www.federation.org.au/level-1/level-1-metadata.xml
    export JAVA_HOME=/usr/local/jdk1.5.0_03
    export IDP_HOME=/usr/local/shibboleth-idp
    export OUTPUT_FILE=/usr/local/shibboleth-idp/etc/level-1-metadata.xml

    $IDP_HOME/bin/metadatatool -i $METADATA_URL \
       -k /etc/cron.hourly/testfed-keystore.jks -a www.federation.org.au -p testfed \
       -o $OUTPUT_FILE

• You will need to modify the variables in the script to match your system installation of Shibboleth IDP (IDP_HOME), Java installation (JAVA_HOME) and metadata file name to be used by your Shibboleth IdP (OUTPUT_FILE). If you are in Level 2 of the Testbed Federation, the METADATA_URL for the metadata is https://www.federation.org.au/level-2/level-2-metadata.xml while the URL for Level 3 metadata is https://www.federation.org.au/level-3/level-3-metadata.xml
• Make sure the script is executable.

For Shibboleth SP

Shibboleth SP is shipped with the siterefesh tool located in $SP_HOME/sbin directory. $SP_HOME refers to the installation directory of Shibboleth SP. The metadatatool can be used to download and verify the metadata signature against a given certificate. The steps for a configuring a Shibboleth SP to receive new metadata on a hourly basis on a Debian system are:

• Prerequisites - You have successfully built and installed Shibboleth SP.
• Download the TestFed website certificate and place it the same directory as your script below.
• Create a script called sp-metadata with the following content and place it in /etc/cron.hourly directory

    #!/bin/bash

    export METADATA_URL=http://www.federation.org.au/level-1/level-1-metadata.xml
    export SP_HOME=/usr/local/shibboleth-sp
    export OUTPUT_FILE=/usr/local/shibboleth-sp/etc/shibboleth/level-1-metadata.xml

    $SP_HOME/sbin/siterefresh --url $METADATA_URL --cert /etc/cron.hourly/www.federation.org.au.pem \
        --out $OUTPUT_FILE

• You will need to modify the variables in the script to match your system installation of Shibboleth SP (SP_HOME), and metadata file name to be used by your Shibboleth SP (OUTPUT_FILE). If you are in Level 2 of the Testbed Federation, the METADATA_URL for the metadata is http://www.federation.org.au/level-2/level-2-metadata.xml while the URL for Level 3 metadata is http://www.federation.org.au/level-3/level-3-metadata.xml
• Make sure the script is executable.

Poor-Man Solution for metadata update

Another alternative of getting the metadata is by simply using wget. This assumes that you can fully trust what the federation site is providing you (use it on your own risk).

Use this only when none of the above approach works for you as temporary measure (and in the meantime contact support for solutions)

• putting a script on your /etc/cron.hourly/metadata-fetch
• the script contains

   wget https://www.federation.org.au/level-1/level-1-metadata.xml -O /usr/local/shibboleth-idp/etc/level-1-metadata.xml
   cp /usr/local/shibboleth-idp/etc/level-1-metadata.xml /usr/local/shibboleth-sp/etc/shibboleth/level-1-metadata.xml

to top