232 lines
7.6 KiB
Plaintext
232 lines
7.6 KiB
Plaintext
Automated Metadata Management
|
||
=============================
|
||
|
||
<!--
|
||
This file is written in Markdown syntax.
|
||
For more information about how to use the Markdown syntax, read here:
|
||
http://daringfireball.net/projects/markdown/syntax
|
||
-->
|
||
|
||
* Version: `$Id: simplesamlphp-automated_metadata.txt 3034 2012-02-16 07:30:11Z olavmrk $`
|
||
|
||
<!-- {{TOC}} -->
|
||
|
||
Introduction
|
||
------------
|
||
|
||
If you want to connect an Identity Provider, or a Service Provider to a **federation**, you need to setup metadata for the entries that you trust. In many federation, in particular federations based upon the Shibboleth software, it is normal to setup automated distributed metadata using the SAML 2.0 Metadata XML Format.
|
||
|
||
Some central administration or authority, provides a URL with a SAML 2.0 document including metadata for all entities in the federation.
|
||
|
||
This document explains how to setup automated downloading and parsing of a metadata document on a specific URL.
|
||
|
||
|
||
|
||
Preparations
|
||
------------
|
||
|
||
You need to enable the following modules:
|
||
|
||
1. cron
|
||
2. metarefresh
|
||
|
||
The cron module allows you to do tasks regularly, by setting up a cronjob that calls a hook in simpleSAMLphp.
|
||
|
||
The metarefresh module will download and parse the metadata document and store it in cached local metadata files.
|
||
|
||
You also need to copy the `config-templates` files from the two modules above, into the global `config/` directory.
|
||
|
||
[root@simplesamlphp] cd /var/simplesamlphp
|
||
[root@simplesamlphp simplesamlphp] touch modules/cron/enable
|
||
[root@simplesamlphp simplesamlphp] cp modules/cron/config-templates/*.php config/
|
||
[root@simplesamlphp simplesamlphp] touch modules/metarefresh/enable
|
||
[root@simplesamlphp simplesamlphp] cp modules/metarefresh/config-templates/*.php config/
|
||
|
||
|
||
|
||
Testing to parse the metadata document
|
||
--------------------------------------
|
||
|
||
We'll use the SWITCH AAI Test Federation as an example in this document. This federation provides metadata on this URL:
|
||
|
||
http://metadata.aai.switch.ch/metadata.aaitest.xml
|
||
|
||
I reccomend to first test on the command line to parse the metadata URL.
|
||
|
||
cd modules/metarefresh/bin
|
||
./metarefresh.php -s http://metadata.aai.switch.ch/metadata.aaitest.xml
|
||
|
||
We use the `-s` option to send output to console (for testing purposes). If the output makes sense, continue. If you get a lot of error messages, send an e-mail to the simpleSAMLphp list and ask for advice.
|
||
|
||
|
||
Below is the documentation provided by Nuno Gonçalves <nuno@fccn.pt>
|
||
|
||
|
||
|
||
|
||
Configuring the cron module
|
||
---------------------------
|
||
|
||
|
||
At `/var/simplesamlphp/config`
|
||
|
||
[root@simplesamlphp-teste config]# vi module_cron.php
|
||
|
||
edit:
|
||
|
||
$config = array (
|
||
'key' => 'kb10fu2sao',
|
||
'allowed_tags' => array('daily', 'hourly', 'frequent'),
|
||
'debug_message' => TRUE,
|
||
'sendemail' => TRUE,
|
||
|
||
);
|
||
|
||
Then: With your browser go to => https://simplesamlphp_machine/simplesaml/module.php/cron/croninfo.php
|
||
|
||
And copy the cron's sugestion:
|
||
|
||
-------------------------------------------------------------------------------------------------------------------
|
||
Cron is a way to run things regularly on unix systems.
|
||
|
||
Here is a suggestion for a crontab file:
|
||
|
||
# Run cron [daily]
|
||
02 0 * * * curl --silent "https://simplesamlphp-teste.fccn.pt/simplesaml/module.php/cron/cron.php?key=kb10fu2sao&tag=daily" > /dev/null 2>&1
|
||
# Run cron [hourly]
|
||
01 * * * * curl --silent "https://simplesamlphp-teste.fccn.pt/simplesaml/module.php/cron/cron.php?key=kb10fu2sao&tag=hourly" > /dev/null 2>&1
|
||
# Run cron [frequent]
|
||
XXXXXXXXXX curl --silent "https://simplesamlphp-teste.fccn.pt/simplesaml/module.php/cron/cron.php?key=kb10fu2sao&tag=frequent" > /dev/null 2>&1
|
||
Click here to run the cron jobs:
|
||
|
||
Run cron [daily]
|
||
Run cron [hourly]
|
||
Run cron [frequent]
|
||
-------------------------------------------------------------------------------------------------------------------
|
||
|
||
Add to CRON with
|
||
|
||
[root@simplesamlphp config]# crontab -e
|
||
|
||
|
||
|
||
Errors
|
||
------
|
||
|
||
Problem with sanitycheck module
|
||
|
||
When executing [Run cron [daily]] ==> an error shows up
|
||
|
||
Cause : module sanitycheck ==> It is active by default (`/var/simplesamlphp/modules/sanitycheck/default-enable`)
|
||
|
||
* When executing Cron daily It will search all active modules and it executes the hook_cron.php for each one of them in :
|
||
`/var/simplesamlphp/modules/<nome_modulo>/hooks/hooks_cron.php`
|
||
|
||
Meanwhile it is waiting that each module conf file exists in the folder: `/var/simplesamlphp/config/config-<nome_modulo>.php`
|
||
|
||
It should exist one for the sanitycheck module => `config-sanitycheck.php` but it wasn't there and therefore the error showed up.
|
||
|
||
Giving an error at this modules it aborted execution for the next active modules.
|
||
|
||
|
||
|
||
Configuring the metarefresh module
|
||
----------------------------------
|
||
|
||
|
||
At `/var/simplesamlphp/config/`
|
||
|
||
|
||
[root@simplesamlphp config]# vi config-metarefresh.php
|
||
|
||
edit:
|
||
|
||
$config = array( 'sets' => array(
|
||
|
||
'kalmar' => array(
|
||
'cron' => array('hourly'),
|
||
'sources' => array(
|
||
array(
|
||
'src' => 'https://kalmar.feide.no/simplesaml/module.php/aggregator/?id=kalmarcentral&mimetype=text/plain&exclude=norway',
|
||
'validateFingerprint' => '591d4b4670463eeda91fcc816dc0af2a092aa801',
|
||
'template' => array(
|
||
'tags' => array('kalmar'),
|
||
'authproc' => array(
|
||
51 => array('class' => 'core:AttributeMap', 'oid2name'),
|
||
),
|
||
),
|
||
),
|
||
),
|
||
'expireAfter' => 60*60*24*4, // Maximum 4 days cache time.
|
||
'outputDir' => 'metadata/federation/',
|
||
|
||
/*
|
||
* Which output format the metadata should be saved as.
|
||
* Can be 'flatfile' or 'serialize'. 'flatfile' is the default.
|
||
*/
|
||
'outputFormat' => 'flatfile',
|
||
),
|
||
));
|
||
|
||
TEMPLATE FILE : /var/simplesamlphp/modules/metarefresh/config-templates/config-metarefresh.php
|
||
|
||
|
||
The configuration consists of one or more metadata sets. Each metadata
|
||
set has its own configuration. The following options are available:
|
||
|
||
`cron`
|
||
: Which of the cron tags will refresh this metadata set.
|
||
|
||
`sources`
|
||
: An array of metadata sources which will be included in this
|
||
metadata set. The contents of this option will be described in more
|
||
detail later.
|
||
|
||
`expireAfter`
|
||
: The maximum number of seconds a metadata entry will be valid.
|
||
|
||
`outputDir`
|
||
: The directory where the generated metadata will be stored. The path
|
||
is relative to the simpleSAMLphp base directory.
|
||
|
||
`outputFormat`
|
||
: The format of the generated metadata files. This must match the
|
||
metadata source added in `config.php`.
|
||
|
||
Each metadata source has the following options:
|
||
|
||
`src`
|
||
: The source URL where the metadata will be fetched from.
|
||
|
||
`validateFingerprint`
|
||
: The fingerprint of the certificate used to sign the metadata. You
|
||
don't need this option if you don't want to validate the signature
|
||
on the metadata.
|
||
|
||
`template`
|
||
: This is an array which will be combined with the fetched metadata to
|
||
generate the final metadata array.
|
||
|
||
|
||
After you have configured the metadata source, you need to give the
|
||
web-server write access to the output directory. Depending on the
|
||
platform, this may be done by a command similar to:
|
||
|
||
chown www-data /var/simplesamlphp/metadata/metadata-federation/
|
||
|
||
Then configure your simpleSAMLphp installation to use the generated metadata:
|
||
|
||
In config.php:
|
||
|
||
'metadata.sources' => array(
|
||
array('type' => 'flatfile'),
|
||
array('type' => 'flatfile', 'directory' => 'metadata/federation'),
|
||
),
|
||
|
||
|
||
Metadata cacheDuration
|
||
----------------------
|
||
|
||
SAML metadata may supply a cacheDuration attribute which indicates the maxium time to cache metadata. Because this module is run from cron, it cannot influence how often it is run and enfore this attribute by itself. Take care that you run metarefresh from cron at least as often as the shortest cacheDuration in your metadata sources.
|
||
|