This document is still in its draft form, any comments welcome
The main function of eduGAIN is to act as a trusted exchange service of information required for interfederation to work. This document describes the methods used to facilitate interfederation based on SAML and must be seen as an addition to the eduGAIN SAML Profile document [eduGAIN-Profile].
The current mode of operations of the eduGAIN SAML profile is to collect entities from participating federations provided in the form of federation aggregates, combine them into a single aggregate and republish. The aggregation process also serves as a validation service in order to ensure that the resulting global aggregate conforms to all required standards.
This central component of eduGAIN is called Metadata Distribution service (MDS).
As specified in [eduGAIN-Profile], in order to publish its entities in eduGAIN a participating federation needs to provide:
A channel to fetch the Federation aggregate from - an http or https location.
An RSA public key with which the metadata document will be signed. This will normally be made available in the form of an X.509 certificate.
The registrationAuthority value to be associated with the channel.
This information needs to be registered with eduGAIN OT in a trust preserving way as described in [eduGAIN-OPS].
In order to eliminate unnecessary traffic, the http/https server serving the aggregate location SHOULD support the Conditional GET Request, this way signalling that the federation aggregate has not been changed.
After a successful verification, each federation aggregate is saved for possible future use.
If a federation aggregate channel is unavailable or fails a required condition it is rejected in full. The latest saved copy is used instead, provided that it is permitted by the value of the validUntil attribute.
If a saved aggregate copy exists and it also follows from the Conditional GET Request that the upstream aggregate has not changed, the saved copy is being used for further processing.
An upstream channel which cannot deliver a document (fetched or from cache) that meets all of the required tests is regarded as empty.
As specified by the [eduGAIN-Profile] in order to assure metadata integrity and originality, each federation aggregate MUST be signed as specified in [SAMLMeta]. This signature made with the key matching the one supplied to the eduGAIN OT is the only element on which trust is based. In particular the eduGAIN aggregator does not use trust that might be derived from an https endpoint details.
Metadata signature verification is done against the public key alone. If the public key for the channel is supplied in the form of an X.509 certificate, other aspects of the certificate such as its expiry date do not form part of signature verification. This is in accordance with the SAML metadata interoperability profile. In particular an expired certificate will still be used for the verification purpose.
condition evaluated | reason | |
|---|---|---|
S1 | The signature exists and is valid | eduGAIN-profile |
S2 | The signature was made with the public key configured for the channel | eduGAIN-profile |
S3 | The signature RSA key size is at least 2048-bit | eduGAIN-profile |
In the verification process the following criteria of the XML signature are also considered, however at the moment they are not considered to be fatal errors. (some items on this list may be moved to the table above if eduGAIN policy makes them mandatory)
The signature was made using an explicit ID reference, not an empty reference.
The signature reference refers to the document element (this helps to avoid "wrapping attacks").
The digest algorithm is at least as strong as SHA-256. Specifically, MD5 and SHA-1 are not permitted as digest algorithms.
The signature method is RSA with an associated digest at least as strong as SHA-256. Specifically, MD5 and SHA-1 are not permitted as digest algorithms.
The signature's transforms contain only permissible values:
Enveloped signature
Exclusive canonicalisation with or without comments
After a positive verification of integrity and originality, the following verification is performed:
condition evaluated | reason | |
|---|---|---|
A1 | the document element is md:EntitiesDescriptor | |
A2 | all required namespaces are declared, that is xmlns:md, xmlns:mdrpi, xmlns:ds. | |
A3 | if md:EntitiesDescriptor contains md:Extensions element with mdrpi:PublicationInfo element in which the publisher attribute is given | |
A4 | validUntil attribute in EntitiesDescriptor element exists, can be converted to a time value and it does not point to the past | SAML lines: 348; 316 |
A5 | validUntil attribute with a value not earlier than 120 hours (5 days) and not later than 2304 hours (28 days) after the creationInstant | eduGAIN-profile |
A6 | the fetched document schema-validates against following SAML metadata schemas:
|
For each md:EntityDescriptor element the following verification is performed:
condition evaluated | reason | |
E1 | entityId attribute value has no space characters, starts with http:// or https:// or urn: and must be unique within given feed | SAMLmeta, ^anyURI |
E2 | md:Extensions element with mdrpi:RegistrationInfo is defined and registrationAuthority attribute matches the value registered with the eduGAIN OT for a given federation | eduGAIN-profile |
E3 | if within md:ContactPerson element any of the following elements is declared: GivenName, Surname, EmailAddress, TelephoneNumber - its values must not be empty | SAMLmeta, ^string |
E4 | if md:Organization element is declared with md:OrganizationDisplayName and/or md:OrganizationName and/or md:OrganizationURL elements then values of these elements must not be empty | SAMLmeta, ^anyURI ^string |
^anyURI - see [SAML] 1.3.2
^string - see [SAML] 1.3.1
For each role descriptor element declared under md:EntityDescriptor the following verification is performed:
condition evaluated | reason | |
R1 | md:IDPSSODescriptor element must have a signing certificate (ds:KeyDescriptor/ds:KeyInfo/ds:X509Data/ds:X509Certificate) | |
R2 | if md:Extentions element with md:UIInfo exists:
| |
R3 | if md:Extentions element with md:DiscoHints exist:
|
Federation aggregates are combined into a single collection - the eduGAIN aggregate as described in detail later. If an md:EntityDescriptor/@entityID value appears in more than one federation aggregate, the resulting collection will contain only one of the entities; the others will be discarded. The aggregator does not attempt to merge or otherwise combine the clashing entity descriptions. See the technical details for a description of the collision handling algorithm.
For each entity document the following are removed:
*/@xml:base
md:EntityDescriptor/@ID
md:EntityDescriptor/@validUntil
md:EntityDescriptor/@cacheDuration
The aggregate md:EntitiesDescriptor element sets the following attributes:
name is set to http://edugain.org
validUntil is set 96 hours into the future
cacheDuration is set to 6h
The eduGAIN aggregate is signed in conformance to the signature profile described in section 3.1 of [SAMLMeta]. In particular the signature:
In the case when
a federation aggregate is unavailable (the corresponding channel is not responding)
a federation aggregate does not validate correctly
an alert is raised and delivered in the form of an e-mail to the Operational Team. An error status is set on the eduGAIN status page https://technical.edugain.org/status and the cause of the error is displayed in the details section. The remaining cache time is also displayed. The status is also available trough the eduGAIN access API, a described on: https://technical.edugain.org/monitoring. If the error condition persists reminder messages are sent in the intervals of 6 hours. If the aggregate can be accessed/validated again, a recovery message is mailed to the OT.
During every aggregation run the validUntil timer for each of the federation aggregates is performed.
Federation public keys, federation aggregates locations (metadata URL), registrationAuthority strings are stored in the eduGAIN database.
Aggregation process is run half past every hour and is performed in the following steps:
all federations with the status “in production” are selected from the eduGAIN database
for each federation its metadata URL is used to access federation metadata feed
the metadata URL is contacted by presenting If-None-Match and If-Modified-Since header values from the last successful metadata fetching process (conditional GET support)
the response 304 means that metadata was not modified - in this case the latest saved copy is used in aggregation process
the response 200 means that a new metadata feed is available
the eduGAIN validator is run against any new metadata feed
any feed error generated by the eduGAIN validator triggers the appropriate report, the offending metadata is rejected and the last successful saved copy is used instead if it is still valid
any successfully checked metadata feed is saved locally
Each freshly downloaded federation aggregate is processed in order to verify integrity and originality and the adherence to all required standards and policy conditions.
Signature verification is handled with the Shibboleth Metadata Aggregator v. 0.9.2
Schema conformance validation is handled with the Shibboleth Metadata Aggregator v. 0.9.2
Additional conditions, in particular those defined by the [eduGAIN-Profile] are handled by eduGAIN specific code in the eduGAIN validator implemented in Python with lxm and OpenSSL modules.
All valid federation aggregates are passed to the aggregator in a sequence ordered according to the date when federations have started to supply data to eduGAIN. During aggregation the first occurrence of a given entityId will be used in the resulting eduGAIN aggregate, any of the following occurrences will be discarded.
It should be noted that this algorithm makes it possible that an entity being served by one federation will be later replaced by its version from another federation if this latter federation comes first in the processing order.
Metadata aggregation is performed with pyFF (currently 0.10.0dev)
This document borrow heavily from Ian Young’s https://gist.github.com/iay/7486653
[SAML] https://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf
[SAMLMeta] https://docs.oasis-open.org/security/saml/v2.0/saml-metadata-2.0-os.pdf
[eduGAIN-Profile]
[eduGAIN-OPS]