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. Further information on the configuration of the Shibboleth Metadata Aggregator can be found on: https://wiki.shibboleth.net/confluence/display/MA1/

Shibboleth Metadata Aggregator (MDA)

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 a Java Runtime (OpenJDK 8 or newer is recommended) is installed.
It is assumed that the installation directory will be ‘/opt/eduGAIN-Metadata-Processing’. 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 0.9.2. Please perform a search-and-replace on this document in case a newer version is available. If the version number differs from 0.9.2 the configuration in mda.xml may have to be adapted. Please inform the author if you find inconsistencies in newer versions.

First, download the directory structure and the necessary files for this distribution. Download the file: EduGAIN-Metadata-Processing.zip
Unarchive the distribution:
unzip eduGAIN-Metadata-Processing.zip
Change the working directory:
cd eduGAIN-Metadata-Processing
Download latest version of the Shibboleth Metadata Aggregator Command Line Interface:
wget http://shibboleth.net/downloads/metadata-aggregator/latest/aggregator-cli-0.9.2-bin.zipwget http://shibboleth.net/downloads/metadata-aggregator/latest/aggregator-cli-0.9.2-bin.zip.asc
Verify fingerprint of the downloaded ZIP file:
gpg aggregator-cli-0.9.2-bin.zip.asc
The resulting output should be that the signature was created by “Ian A. Young <ian@iay.org.uk>” with key D7079C77.
Unarchive the downloaded file
unzip aggregator-cli-0.9.2-bin.zip
Create a symlink
ln -s aggregator-cli-0.9.2 aggregator-cliIn order to verify eduGAIN metadata, it is necessary to provide the eduGAIN signing certificate to the Metadata Aggregator.
Check the signature of the eduGAIN signer certificate:
openssl x509 -fingerprint -in pki/eduGAIN-signer-ca.pemThe SHA1 Fingerprint should be 8B:81:7A:0C:F3:F8:35:2F:85:91:9F:11:37:14:3F:98:91:8C:F8:34
Adapt the main configuration in conf/mda.properties
This file allows a very simple configuration of the eduGAIN Metadata Processing tool by setting a few properties. These properties then are used in the conf/mda.xml file that is a standard Spring context. More advanced configuration can be done directly in the file mda.xml. In the mda.properties file the parameters BasePath, EntitiesDescriptor, RegistrationAuthorityFilter, SigningKey and SigningCert should be set at minimum.

Create run script

Open the file ‘bin/run-mda.sh’ in a text editor and edit the parameters. In particular edit BASE_PATH, JAVA_HOME

Make the file run file and the cron job files executable:
chmod a+x bin/run-mda.sh
chmod a+x cron-jobs/run-mda

Test deployment

Run the Metadata Aggregator
./bin/run-mda.shThe 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 pki/example-signer-cert.pem

Install Cronjob to run job regularly

Adapt the file cron-jobs/run-mda In particular change the email address of the MAILTO variabe
Move the file cron-jobs/run-mda to /etc/cron.d/ to run the metadata aggregator regularily.

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.

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 2.7 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 0.9.4. Please perform a search-and-replace on this document in case a newer version is available. Please inform the author if you find inconsistencies in newer versions.

Follow the instructions provided by pyFF Documentation to install pyFF software.
Create the needed directories:
cd /opt/pyff ; mkdir output ; mkdir certs ; mkdir scripts
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
Download and Check the eduGAIN Signer certificate:
wget https://www.edugain.org/mds-2014.cer -O /opt/pyff/certs/eduGAIN-signer-ca.pem
Check the signature of the eduGAIN signer certificate:
openssl x509 -fingerprint -in /opt/pyff/certs/eduGAIN-signer-ca.pemThe SHA1 Fingerprint should be 8B:81:7A:0C:F3:F8:35:2F:85:91:9F:11:37:14:3F:98:91:8C:F8:34
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
   - http://mds.edugain.org/feed-sha256.xml as edugain-md certs/eduGAIN-signer-ca.pem
   # Load from a specific directory contains the eduGAIN Metadata
   #- /opt/pyff/metadata as edugain-md certs/eduGAIN-signer-ca.pem
 
### Replace the value of '###YOUR-REG-AUTH###' with your registrationAuthority to exclude the entities of your federation. ###
- select:
   - "edugain-md!//md:EntityDescriptor[md:Extensions/mdrpi:RegistrationInfo/@registrationAuthority and not(md:Extensions/mdrpi:RegistrationInfo/@registrationAuthority='###YOUR-REG-AUTH###')]"
 
### Remove comments and replace 'entityID_X' with the entityID of the eduGAIN entities that you want exclude from your interfederation metadata. ###
#- fork merge remove:
#   - select:
#      - entityID_1
#      - entityID_2
 
### 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
 
### 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

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.shThe 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 metadadata 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.

Useful notes

The version 0.9.4 of pyff signing the output metadata with SHA-1 algorithm by default.
If you want to sign the metadata with another algorithm supported by the software, you must replace the value of 'ALGORITHM_SIGNATURE_RSA_SHA1' and 'ALGORITHM_DIGEST_SHA1' inside the '/opt/pyff/lib/python2.7/site-packages/xmlsec/__init__.py' file with one of these values:

SHA1: 'ALGORITHM_SIGNATURE_RSA_SHA1' and 'ALGORITHM_DIGEST_SHA1'
SHA256: 'ALGORITHM_SIGNATURE_RSA_SHA256' and 'ALGORITHM_DIGEST_SHA256'
SHA384: 'ALGORITHM_SIGNATURE_RSA_SHA384' and 'ALGORITHM_DIGEST_SHA384'
SHA512: 'ALGORITHM_SIGNATURE_RSA_SHA512' and 'ALGORITHM_DIGEST_SHA512'