Skip to content
Snippets Groups Projects
Commit cc142f41 authored by Jaime Perez's avatar Jaime Perez
Browse files

aggregator2: update the documentation to reflect the latest changes and features.

parent 82610a4d
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
modules/aggregator2/docs/aggregator2.txt
+ 102
− 49
View file @ cc142f41
aggregator2 Module
==================
This is an experimental module for aggregating metadata.
It is designed to preserve most of the common metadata items, and also attempt to preserve unknown elements.
This is a module for metadata aggregation. It is designed to preserve most of the common metadata items, and it also
attempts to preserve unknown elements. Metadata sources are parsed and rebuilt, so small differences between the
original sources and the metadata generated may occur. More specifically:
*Note*: This aggregator only works on XML metadata, and does its work independently of the of other parts of simpleSAMLphp, such as the `metarefresh` module.
* Signatures will be removed from every signed metadata source.
* All sources will be wrapped up in an `EntitiesDescriptor` element.
*Note*: This aggregator works only with XML metadata, and does its work independently of other parts of SimpleSAMLphp,
such as the `metarefresh` module.
Configuration
......@@ -13,11 +18,10 @@ Configuration
This module is configured through the `config/module_aggregator2.php` configuration file.
An example file is available in `modules/aggregator2/config-templates/`:
cd /var/simplesaml
cp modules/aggregator2/config-templates/module_aggregator2.php config/
The configuration file contains one or more aggregators in the configuration array.
The index in the configuration array gives the identifier of the aggregator.
The index for each item in the configuration array gives the identifier of the aggregator.
### Aggregator entry configuration
......@@ -25,52 +29,87 @@ The index in the configuration array gives the identifier of the aggregator.
The aggregator can be configured with the following options:
`sources`
: Array which describes which metadata we should download.
: Array which describes a source from which we should download metadata.
`cron.tag`
: Can be used to periodically run an update.
Only useful when you have enabled caching of metadata.
: Can be used to run periodical updates. It will only be useful when you have metadata caching enabled.
`cache.directory`
: A path to a directory where the aggregator will cache downloaded and generated metadata.
This directory must be writeable by the webserver.
: The path to a directory where the aggregator will cache downloaded and generated metadata.
This directory must be writable by the web server.
`cache.generated`
: The number of seconds generated metadata should be cached.
If this option is unset, the generated metadata will not be cached.
: The number of seconds the generated metadata will be cached for.
: *Note*: generated metadata will not be cached if this option is unset.
`valid.length`
: The number of seconds the generated metadata should be valid.
This is used to set the validUntil attribute on the generated metadata.
The default is one week.
: The number of seconds the generated metadata should be valid for.
This is used to set the `validUntil` attribute on the generated metadata.
Defaults to one week..
: *Note*: The `cache.generated` option must be smaller than this option, otherwise you will end up returning outdated metadata.
: *Note*: The value of the `cache.generated` option must be smaller than the value here, otherwise you would end up
returning outdated metadata.
`ssl.cafile`
: This option enables validation of the server certificate when fetching metadata over https.
It must be set to a path to a PEM-file which contains one or more valid CA certificates.
The path can be absolute, or it can be relative to the `cert`-directory.
: This option enables validation of the server certificate when fetching metadata over HTTPS. It must be a path
pointing to a PEM file which contains one or more valid CA certificates. The path can be either absolute or
relative to the `cert` directory.
: *Note*: This option can be overridden for each metadata source.
`sign.privatekey`
: The private key that should be used to sign the metadata, in PEM format.
The path to the private key can be absolute, or it can be relative to the `cert`-directory. Skip this option or
set it to NULL if you don't want to sign the generated metadata.
: The private key that should be used to sign the resulting metadata, in PEM format. The path to the private key can
be either absolute or relative to the `cert` directory. Skip this option or set it to `NULL` if you don't want to
sign the generated metadata.
`sign.privatekey_pass`
: The password for the private key.
If this option is unset, the private key is assumed to be unencrypted.
: The password used to encrypt the private key. If this option is unset, the private key is assumed to be unencrypted.
`sign.certificate`
: The certificate which contains the public key corresponding to the private key, in PEM format.
This certificate is included in the generated metadata.
The path to the certificate can be absolute, or it can be relative to the `cert`-directory.
: The certificate that contains the public key corresponding to the private key, in PEM format. The path to the
certificate can be either absolute or relative to the `cert` directory.
: *Note*: This certificate will be included in the generated metadata.
`RegistrationInfo`
: Allows to specify information about the registrar of this metadata. Please refer to the
: Allows to specify information about the registrar of the generated metadata. Please refer to the
[MDRPI extension](./simplesamlphp-metadata-extensions-rpi) document for further information.
`exclude`
: Allows to exclude one or more entities from the generated metadata, represented by their entity IDs. Can be either
a string with the entity ID of a single entity, or an array of strings with all the entity IDs to exclude from
the result.
: *Note*: this option will not exclude the entities from the cached metadata sources. It will only act as a default
configuration for the generation of the metadata aggregate, and therefore can be overridden per request.
`filter`
: One or more sets representing the types of entities that should be included in the generated metadata. Filtering
will be performed depending on the role of the entity, as well as the protocols it supports. Can be either a string
with the set of entities desired, or an array of strings with all the different sets to filter by. The following
sets are available:
* `saml2`
: All the entities that support the SAML 2.0 protocol.
* `shib13`
: All the entities that support the SAML 1.1 protocol.
* `saml20-idp`
: All the identity providers that support the SAML 2.0 protocol.
* `saml20-sp`
: All the service providers that support the SAML 2.0 protocol.
* `saml20-aa`
: All the attribute authorities that support the SAML 2.0 protocol.
* `shib13-idp`
: All the identity providers that support the SAML 1.1 protocol.
* `shib13-sp`
: All the service providers that support the SAML 1.1 protocol.
* `shib13-aa`
: All the attribute authorities that support the SAML 1.1 protocol.
: *Note*: this option will not filter the entities in the cached metadata sources. It will only act as a default
configuration for the generation of the metadata aggregate, and therefore can be overriden per request.
### Aggregator source configuration
......@@ -78,41 +117,55 @@ The aggregator can be configured with the following options:
: The URL the metadata should be fetched from.
`ssl.cafile`
: This option enables validation of the server certificate when fetching metadata over https.
It must be the path to a PEM-file which contains one or more valid CA certificates.
The path can be absolute, or it can be relative to the `cert`-directory.
: This option enables validation of the server certificate when fetching metadata over HTTPS. It must be a path
pointing to a PEM file which contains one or more valid CA certificates. The path can be either absolute or
relative to the `cert` directory.
: *Note*: This option overrides the aggregator option.
: *Note*: This option overrides the option with the same name in the root configuration for the an aggregator.
`cert`
: Check the signature on the metadata against the specified certificate.
The path to the certificate can be absolute, or it can be relative to the `cert`-directory.
: The certificate that should be used to check the signature of this metadata document, in PEM format. The path to
the certificate can be either absolute or relative to the `cert` directory.
: *Note*: This can not be a CA certificate.
Validation against a CA certificate is not supported.
: *Note*: This cannot be a CA certificate. Validation against CA certificates (PKI) is not supported.
Retrieving aggregated metadata
------------------------------
The metadata can be downloaded from the following location:
You will find a link to the aggregator2 module in the *Federation* tab of SimpleSAMLphp's web interface. There you will
be able to see a list of all the metadata aggregates you have configured, and see or download them in different
formats.
In general, metadata aggregates can be downloaded from the following location:
http://<YOUR HOST>/simplesaml/modules.php/aggregator2/get.php?id=<aggregator id>
where the *aggregator id* is the identifier you used as an index for the aggregator configuration array. Additionally,
you can use the following parameters to customize the resulting metadata aggregate:
`exclude`
: Allows to exclude one or more entities from the generated metadata, represented by their entity IDs. If you need to
specify more than one entity, use a comma-separated list of entity IDs.
http://<server>/simplesaml/modules.php/aggregator2/get.php?id=<aggregator id>
`filter`
: Allows to filter by sets specifying the type of entities or the protocols they support. If you need to specify more
than one set, use a comma-separated list. See the configuration option with the same name to get a list of all
the sets supported.
Asynchronous metadata updates
-----------------------------
By default, the `aggregator2` module will update the metadata when receiving a request.
For performance reasons, it is recommended to run the updates asynchronously.
By doing this, the aggregated metadata will be generated in the background.
By default, the `aggregator2` module will update the metadata upon receiving a request. For performance reasons, it is
recommended to run the updates asynchronously. By doing this, the aggregated metadata will be generated in the
background.
To enable this, you must configure a cache directory with the `cache.directory` option.
This directory must be writeable by the web server.
You can then enable caching of generated metadata by setting the `cache.generated` option to the number of seconds the metadata can be cached.
To enable this, you must configure a cache directory with the `cache.directory` option. This directory must be writable
by the web server. You can then enable caching of generated metadata by setting the `cache.generated` option to the
number of seconds the metadata should be cached.
You will now have a configuration that caches both downloaded and generated metadata.
It will however still update the metadata when the user accesses the aggregator endpoint
To update the generated metadata in the background, you must add a `cron.tag` option.
This option must reference a cron tag entry configured in `module_cron.php`.
Once this is done, your aggregated metadata will be updated everytime that cron entry is executed.
You will now have a configuration that caches both downloaded and generated metadata. However, it will still update the
metadata when the user accesses the aggregator endpoint. To update the generated metadata in the background, you must
add a `cron.tag` option. This option must reference a cron tag entry configured in `module_cron.php`. Once this is
done, your aggregated metadata will be updated every time that cron entry is executed.
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment