Introduction

This quick install guide explains how a SAML based identity federation can deploy a Shibboleth Metadata Aggregator, or a pyFF Federation Feeder, in order to download, process and republish metadata. This is in particular useful in the context of eduGAIN where it is recommended that participating federations download metadata from mds.edugain.org, process and republish it for their local federation. Therefore, this guide will focus on the eduGAIN use case but it can also be used easily for different but similar applications

The default configuration will create three metadata files in the output directory: metadata.interfederation+idp.xml, metadata.interfederation+sp.xml metadata.interfederation.xml. The first two will contain only IdPs or SPs. The default configuration can easily be adapted to meet different requirements.

Shibboleth Metadata Aggregator (MDA)

Up-to-date information on the Shibboleth MDA can be found at https://shibboleth.atlassian.net/wiki/spaces/MA1/overview

Prerequisites and assumptions

• This guide assumes that the administrator is familiar with Linux, editing text based configuration files and running shell commands.
• You have installed openssl and Java 17 (or later). JAVA_HOME is set and exported.
• You have created the /opt/mda directory for installation. Root access might be needed to install this software.
• In order to run cronjobs more securely, an unprivileged user mda-user is recommended to use

Installation

In the following, we assume that the latest version of the metadata aggregator is 1.0.0. Please inform support@edugain.org if you find inconsistencies in newer versions.

1. Download eduGAIN-metadata-example.tar.gz into /opt/mda and unpack the tarfile
2. Download the Shibboleth MDA to /opt/mda, as per the MDA instructions: https://shibboleth.atlassian.net/wiki/spaces/MA1/pages/1476984838/Installation+Guide
3. Unpack the MDA distribution
4. Download the eduGAIN signing certificate from https://technical.edugain.org/metadata
5. Check its integrity and authenticity using openssl x509 -fingerprint -sha256 -in /opt/mda/mds-v2.cer  -noout
6. run eduGAIN-setup.sh to generate signing key and certificate
7. run eduGAIN-run.sh to download and process the eduGAIN metadata aggregate

There should now be three new metadata files in /opt/mda

You can check the signature on these files can be verified using the certificate whose private key was used to sign the file. Using XMLSecTool this can be verified with:

xmlsectool.sh --verifySignature --inFile metadata-all.xml --certificate federation.crt

Post-installation

1. Set up a cron job to run the metadata aggregator regularly
2. Publish the metadata regularly

pyFF Federation Feeder

Prerequisites

• This guide assumes that the administrator is familiar with Linux, editing text based configuration files and running shell commands.
• The guide assumes that the administrator has access to a Linux system where Python  >=3.9 is installed.
• It is assumed that the installation directory will be ‘/opt/pyff’. Root access might be needed to install this software.
• It is assumed that the output metadata directory will be ‘/opt/pyff/output’. Root access might be needed to create this directory.
• In order to run cronjobs more securely, it is recommended to create and use an unprivileged user pyff-user.

Installation

In the following, we assume that the latest version of the pyFF Federation Feeder is 2.1.5. Please perform a search-and-replace on this document in case a newer version is available. Please inform support@edugain.org if you find inconsistencies in newer versions.

1. Follow the instructions provided by pyFF Documentation to install pyFF software.
2. Create the needed directories:
   cd /opt/pyff ; mkdir output ; mkdir certs ; mkdir scripts
3. Create the certificate and the key needed to sign the output metadata:
   - Generate Metadata Signer Key: openssl genrsa -out /opt/pyff/certs/sign.key 2048
   - Generate Metadata Signer Certificate: openssl req -key /opt/pyff/certs/sign.key -new -x509 -days 3650 -out /opt/pyff/certs/sign.crt
4. Download and Check the eduGAIN Signer certificate (see https://technical.edugain.org/metadata):
   wget https://technical.edugain.org/mds-v2.cer -O /opt/pyff/certs/eduGAIN-signer-ca.pem
5. Check the signature of the eduGAIN signer certificate:
   openssl x509 -fingerprint -in /opt/pyff/certs/eduGAIN-signer-ca.pem
The SHA256 Fingerprint should be
   BD:21:40:48:9A:9B:D7:40:44:DD:68:05:34:F7:78:88:A9:C1:3B:0A:C1:7C:4F:3A:03:6E:0F:EC:6D:89:99:95
6. Create the interfederation configuration file(/opt/pyff/interfederation.fd) by adapting this content to your needs:

### Load eduGAIN Metadata ###
- load:
   # Load from the eduGAIN Metadata URL
   - https://mds.edugain.org/edugain-v2.xml as edugain-md certs/eduGAIN-signer-ca.pem
   # If your federation feed has entities that are not published on eduGAIN
   # load your federation feed as well - uncomment the line below
   #- ###YOUR-FEDERATION-FEED-URL### as myfederation-md ###PATH-TO-YOUR-FEDERATION-SIGNING-CERT###

- select:
   - edugain-md
   # If your federation feed has entities that are not published on eduGAIN
   # uncomment the line below
   #- myfederation-md


### Produce the Interfederation Metadata ###
### Replace the value of '###YOUR-ENTITIESDESCRIPTOR-NAME-FOR-INTERFEDERATION###' and '###YOUR-ENTITIESDESCRIPTOR-ID-FOR-INTERFEDERATION###' with the values of XML attributes "Name" and "ID" chosen for your interfederation metadata stream ###
- xslt:
   stylesheet: tidy.xsl
- finalize:
   Name: ###YOUR-ENTITIESDESCRIPTOR-NAME-FOR-INTERFEDERATION###
   ID: ###YOUR-ENTITIESDESCRIPTOR-ID-FOR-INTERFEDERATION###
   cacheDuration: PT5H
   validUntil: P5D
- sign:
   key: certs/sign.key
   cert: certs/sign.crt
- publish:
   - output/my-interfederation-metadata.xml

# The rest of pipe could be removed if you do not plan to publish interfederation feeds which contain
# only SPs (for consuming by IdPs) and only IdPs (for consuming by IdPs)
# Feeds dedicated for IdPs and SPs are a good way to avoid a large feed problem which e.g. requires
# increasing memory_limit for php when simpleSAMLPHP is used
### Fork to produce the Interfederation Identity Providers Metadata ###
### Replace the value of '###YOUR-ENTITIESDESCRIPTOR-NAME-FOR-INTERFEDERATION###' and '###YOUR-ENTITIESDESCRIPTOR-ID-FOR-INTERFEDERATION###' with the values of XML attributes "Name" and "ID" chosen for your interfederation metadata stream ###
- fork:
   - select:
      - "edugain-md!//md:EntityDescriptor[md:IDPSSODescriptor]"
   - xslt:
      stylesheet: tidy.xsl
   - finalize:
      Name: ###YOUR-ENTITIESDESCRIPTOR-NAME-FOR-INTERFEDERATION###
      ID: ###YOUR-ENTITIESDESCRIPTOR-ID-FOR-INTERFEDERATION###
      cacheDuration: PT5H
      validUntil: P5D
   - sign:
     key: certs/sign.key
      cert: certs/sign.crt
   - publish:
      - output/my-interfederation-idp-metadata.xml

### Fork to produce the Interfederation Service Providers Metadata ###
### Replace the value of '###YOUR-ENTITIESDESCRIPTOR-NAME-FOR-INTERFEDERATION###' and '###YOUR-ENTITIESDESCRIPTOR-ID-FOR-INTERFEDERATION###' with the values of XML attributes "Name" and "ID" chosen for your interfederation metadata stream ###
- fork:
   - select:
      - "edugain-md!//md:EntityDescriptor[md:SPSSODescriptor]"
   - xslt:
      stylesheet: tidy.xsl
   - finalize:
      Name: ###YOUR-ENTITIESDESCRIPTOR-NAME-FOR-INTERFEDERATION###
      ID: ###YOUR-ENTITIESDESCRIPTOR-ID-FOR-INTERFEDERATION###
      cacheDuration: PT5H
      validUntil: P5D
   - sign:
      key: certs/sign.key
      cert: certs/sign.crt
   - publish:
      - output/my-interfederation-sp-metadata.xml

Create run script

1) vim /opt/pyff/scripts/run-pyff.sh :

#!/bin/bash
 
. /opt/pyff/bin/activate
 
pyff --loglevel=INFO /opt/pyff/interfederation.fd
 
deactivate

2) chmod a+x /opt/pyff/scripts/run-pyff.sh

Create the Cronjob

• crontab -e :

MAILTO="your.monitoring.address@your.organisation.org"
55 * * * * root su -c /opt/pyff/scripts/run-pyff.sh - pyff-user

Test deployment

Run the pyFF Federation Feeder
./opt/pyff/scripts/run-pyff.sh

The output should be three new metadata files in the ‘output’ directory.
Then check if the signature on these files can be verified using the certificate whose private key was used to sign the file. Using XMLSecTool this can be verified with:

xmlsectool.sh --verifySignature --inFile output/metadata.interfederation.xml --certificate certs/sign.crt

Publish metadata regularly

Install a cron job that moves the eduGAIN metadata from the ‘output’ directory to a web server where the eduGAIN-enabled entities of your federation can download it. Because the metadata is signed, it can also be served on an http site.