How to add the OpenAthens federation to common SP software

If you are already using or are planning on using other SP software within the OpenAthens federation, you will need to make it aware of the OpenAthens federation metadata. Since terminology can sometimes vary, this page will show the federation specific settings for some common SAML SP software.

This page can only be a guide - for up-to-date installation help you should refer to the documentation and provider of whichever software you are using.

First create the application record in the OpenAthens federation.

Shibboleth

Update your shibboleth2.xml file with a metadata provider:

CODE

        <MetadataProvider type="XML" url="http://fed.openathens.net/oafed/metadata"
              backingFilePath="oafed-metadata.xml" reloadInterval="7200">
            <MetadataFilter type="RequireValidUntil" maxValidityInterval="2419200"/>
            <MetadataFilter type="Signature" certificate="oafed-certificate.pem"/>
        </MetadataProvider>

Where oafed-certificate.pem is the x509 certificate from our metadata, saved in the same folder as your shibboleth2.xml file.

OA fed metadata x509 certificate

CODE

SimpleSAMLphp

You will need a signing certificate. Create one in the cert directory:

CODE

cd cert
openssl req -newkey rsa:2048 -new -x509 -days 3652 -nodes -out saml.crt -keyout saml.pem

Refer to it in your authsources.php file:

CODE

'default-sp' => array(
    'saml:SP',
    'privatekey' => 'saml.pem',
    'certificate' => 'saml.crt',
),

Enable the metadata and cron modules:

CODE

touch modules/metarefresh/enable
cp modules/metarefresh/config-templates/*.php config/
touch modules/cron/enable
cp modules/cron/config-templates/*.php config/

Create a directory to cache the metadata:

CODE

mkdir metadata/openathens
chmod go+rw metadata/openathens

Edit config/metadatarefresh.php:

CODE

<?php
$config = array(
    'sets' => array(
        'uk' => array(
            'cron'      => array('hourly'),
            'sources'   => array(
                array(
                    'src' => 'https://fed.openathens.net/oafed/metadata',
                    'validateFingerprint' => '49:EC:EB:FE:CA:2F:F8:A7:74:48:2D:EB:81:9A:5A:0A:B4:02:ED:91',
                ),
            ),
            'expireAfter'       => 60*60*24*1, // Maximum 1 days cache time.
            'outputDir'     => 'metadata/openathens/',
            'outputFormat' => 'serialize',
        ),
    ),
);

Finally set the cache to be a metadata source in config.php:

CODE

'metadata.sources' => array(
    array('type' => 'flatfile'),
    array('type' => 'serialize', 'directory' => 'metadata/openathens'),
),

You will also need to upload your SP metadata in the publisher dashboard when you register your app. Get it from the federation tab on the simpleSAMLphp front page. If you encounter metadata loading issues you may need to increase the memory_limit and max_execution_time in your php configuration file.