| Table of Contents | ||
|---|---|---|
|
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].
...
Technical operational details about metadata signing, publication and other procedures can be found in the eduGAIN Operational Practice statement Document [eduGAIN-OPS].
Terms
The terms defined below are a required extension of the terminology defined in [eduGAIN-Profile]. The reader should consult both dictionaries for a complete picture.
| federation metadata feed | A SAML metadata file originating from a participant Federation acting as a SAMLMetadataProducer |
| federation metadata channel | A location (in the form of http/https URL) pointing to the distribution source of the federation metadata feed |
| eduGAIN matadata aggregate | A SAML metadata filegenerated as an aggregate of federation metadata feeds according to the procedures described in this document |
Source of metadata
MDS bases its aggregation function on information provided by each participant Federation as specified in [eduGAIN-Profile]:
...
In order to eliminate unnecessary traffic, the http/https server serving the federation metadata feed location SHOULD support the Conditional GET Request, this way signalling that the federation metadata feed has not been changed.
Metadata acquisition and validation
General
After a successful verification (as described further down), each federation metadata feed is saved locally for possible future use.
...
A federation metadata channel which cannot deliver a document (fetched or from cache) that passes all of the required tests is regarded as empty.
Verification of origin
As specified by the [eduGAIN-Profile] in order to assure metadata integrity and originality, each federation metadata feed 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 MDS does not use trust that might be derived from an https endpoint details.
...
Condition evaluated | Reason | |
|---|---|---|
S1 | The signature exists and is valid | eduGAIN-profile] section 4 |
S2 | The signature can be validated with the public key configured for the federation metadata channel | [eduGAIN-profile] section 4 |
| S3 | The signature was made using an explicit ID reference, not an empty reference | [eduGAIN-profile] section 4 |
| S4 | The signature reference refers to the document element | [eduGAIN-profile] section 4 |
| S5 | The signature's digest algorithm is at least as strong as SHA-256, and does not use MD5 | [eduGAIN-profile] section 4 |
| S6 | The signature's signature method is RSA with an associated digest at least as strong as | [eduGAIN-profile] section 4 |
| S7 | The signature's transforms contain only these permissible values:
| [eduGAIN-profile] section 4 |
| S8 | RSA/EC key used to sign metadata is at least 2048/256 bits in length | [eduGAIN-profile] section 4 |
Verification of metadata validity
After a positive verification of integrity and originality (as described in the previous section), the following validity verification steps are 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:
| [MDUI] sec. 2.1, [SAML] sec.1.3.1, [SAML] sec.1.3.2 |
R3 | if md:Extentions element with md:DiscoHints exist:
| [MDUI] sec.2.2, [SAML] sec.1.3.1, [SAML] sec .1.3.2, RFC5870 (for geo) |
| R4 | md:ServiceName element within md:AttributeConsumingService is not empty | SAMLMeta 2.4.4.1, SAML 1.3.1 |
| R5 | md:AssertionConsumerService element Binding attribute does not contain urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect | [SAMLProf] sec. 4.1.2 line 424 |
| R6 | md:DiscoveryResponse element Binding attribute contains the value | [IdPDisco] sec.2.5 |
| R7 | indexes in md:DiscoveryResponse, md:AssertionConsumerService, md:AttributeConsuminService are unique | [SAMLMeta] sec.2.2.3 |
Resulting eduGAIN metadata aggregate
Federation metadata feeds are combined into a single collection - the eduGAIN metadata aggregate as described in detail later. If an md:EntityDescriptor/@entityID value appears in more than one federation metadata feed, the resulting collection will contain only one of these entities; the others will be discarded. MDS does not attempt to merge or otherwise combine the clashing entity descriptions. See the technical details for a description of the collision handling algorithm.
...
- is enveloped - http://www.w3.org/2000/09/xmldsig#enveloped-signature
- contains ds:Reference containing a URI reference to the document element's ID attribute
- uses SHA-256 digest method - http://www.w3.org/2001/04/xmlenc#sha256
- uses RSA + SHA-256 signature method - http://www.w3.org/2001/04/xmldsig-more#rsa-sha256
- uses exclusive canonicalisation - http://www.w3.org/TR/2001/REC-xml-c14n-20010315
Alerts and information
In the case when
a federation metadata feed is unavailable (the corresponding federation feed channel is not responding)
a federation metadata feed does not validate correctly
...
- If the remaining validity period is below 96 and above 12 hours an alert is raised once a day at 14 hour UTC.
- If the remaining validity period is below 12 and above 6 hours an alert is raised every second hour.
- If the remaining validity period is below 6 hours an alert is raised every hour.
Detailed technical description
Metadata acquisition
Federation public keys, federation feed channel locations (metadata URL), registrationAuthority strings are stored in the eduGAIN database.
...
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
Metadata validation
Each freshly downloaded federation metadata feed is processed in order to verify integrity and originality and the adherence to all required standards and policy conditions.
...
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.
Metadata combination and collision handling
All valid federation metadata feeds 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 metadata aggregate, any of the following occurrences will be discarded.
...
Metadata aggregation is performed with pyFF (currently 0.10.0dev)
Acknowledgment
This document borrows heavily from Ian Young’s https://gist.github.com/iay/7486653
References
[SAML] https://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf
...