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

  • 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.

  1. First, download the directory structure and the necessary files for this distribution. Download the file: EduGAIN-Metadata-Processing.zip

  2. Unarchive the distribution:

    unzip eduGAIN-Metadata-Processing.zip
  3. Change the working directory:
    cd eduGAIN-Metadata-Processing
  4. 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.zip
    wget http://shibboleth.net/downloads/metadata-aggregator/latest/aggregator-cli-0.9.2-bin.zip.asc
  5. 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.
  6. Unarchive the downloaded file
    unzip aggregator-cli-0.9.2-bin.zip
  7. Create a symlink
    ln -s aggregator-cli-0.9.2 aggregator-cli
    In order to verify eduGAIN metadata, it is necessary to provide the eduGAIN signing certificate to the Metadata Aggregator.
  8. Check the signature of the eduGAIN signer certificate:
    openssl x509 -fingerprint -in pki/eduGAIN-signer-ca.pem
    The SHA1 Fingerprint should be 5A:D7:3F:8A:C1:0C:74:56:41:77:45:45:EB:92:76:1F:3D:0D:E6:7C
  9. 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.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 pki/example-signer-cert.pem

Install Cronjob to run job regularly

  1. Adapt the file cron-jobs/run-mda In particular change the email address of the MAILTO variabe
  2. 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  >=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 the author 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.



  • No labels