This document describes operational procedures implemented to support eduGAIN SAML services and together with the Metadata Aggregation Practice Statement [eduGAIN-meta] should be seen as complementary to eduGAIN SAML Profile.
The list below shows eduGAIN services as perceived by external users. The technical details of how the services are organised are provided in a separate section further down.
| Name | Access location | Description | Managed by |
|---|---|---|---|
| MDS | https://mds.edugain.org | eduGAIN Metadata Distribution Service (MDS) is the central component of the eduGAIN service as a whole. For the detailed description and procedures used in the eduGAIN metadata aggregate distributed by MDS see technical sections below and [eduGAIN-meta]. The aggregated file is updated hourly. | OT |
| The technical site | https://technical.edugain.org | The technical site is directed primarily at the federation level technical personel. It provides information about eduGAIN members, details about their participation. The technical site is also the distribution point of documentation and the home for several core and supplementary services. | OT |
| Validator | https://validator.edugain.org | The eduGAIN validator is a service designed for validating metadata adherence to standards and eduGAIN requirements. The software has been created primarily as a component for the eduGAIN metadata aggregation and the details of validation rules are given in [eduGAIN-meta]. The same software enriched by a GUI is used as a tool for manual validation of metadata and serves as a support tool for federation operators. | OT |
| eduGAIN status information | https://technical.edugain.org/status | This status page provides a view of the eduGAIN database in the part relevant to membership information and the current status of metadata aggregation. The page also displays short summary information about numbers of entities in eduGAIN. The interface provides links to scans of the eduGAIN declaration documents signed by federations, direct links to metadata validation, links to contacts, metadata sources etc. | OT |
| Entities database GUI | http://technical.edugain.org/entities | This service is an interface to the part of the eduGAIN database which stores information about entities themselves. The interface has many filtering mechanisms and also allows for CSV download for further processing in a spreadsheet. | OT |
| eduGAIN database API | https://technical.edugain.org/api | The API provides access to most of information stored in the database. In particular, the API may be used by the federations to monitor the eduGAIN aggregation process. Other uses are statistics of various sorts or even download of membership maps. | OT |
| Name | Access location | Description | Managed by |
|---|---|---|---|
| ECCS | https://technical.edugain.org/eccs/ | eduGAIN Connectivity Check Service is a monitoring service for IdPs listed in eduGAIN, testing if they are actually ready for eduGAIN, i.e. if they consume eduGAIN metadata | OT |
| isFederated Check | https://technical.edugain.org/isFederatedCheck/ | This tool searches all known academic identity federations for matching organisations and then displays the results. | OT |
| CoCo monitor | http://monitor.edugain.org/coco/ | Monitoring service testing for REFEDS Code of Conduct compliance | SRCE |
| Technical testing platform | http://technical-test.edugain.org | This host serves as a playground for software development done by the operational team. All extensions are applied, tested and presented at this platform and then transferred to production using the git mechanism | OT |
| WIKI | The WIKI is maintained as a part of the GEANT WIKI space. The content is provided by many members of the community. WIKI serves as technical documentation, formal documentation (meeting minutes, documentation of operational procedures) and various guides on joining and making most of eduGAIN | GEANT core | |
| Support |
As defined in [eduGAIN-CONST] the Operational Team (OT) is responsible for:
At the moment the OT also acts as the operator of the SAML technology profile.
The joining process support has been assigned to the Operational Team, but decision making and organising the voting process currently lies within the eduGAIN SG and its chair. The OT handles all technical details of joining, like metadata validation, signing certificate handling etc. Any paperwork is handled by the eduGAIN secretariat provided by GEANT.
eduGAIN core function is the metadata exchange point. Federations supply their own metadata and download aggregated metadata to supplement their own and redistribute them within their federation members. Federations are strongly discouraged from pointing any of their members directly to the eduGAIN MDS. The operational baseline of MDS availibility is set at 99% for any given month. The unavailability details are provided at eduGAIN Services Status and system changes are listed at https://technical.edugain.org/system_updates.
While every care is taken that all eduGAIN services function reliably, the selected operational model allows that services updates and modifications can be done at a short-term notice allowing for a small risk of a downtime required to restore the system snapshot.
The security of the eduGAIN SAML services is essentially the security of the eduGAIN aggregate. This in turn depends on:
The procedures to maintain the appropriate level of security are described in the technical sections below.
The eduGAIN database is central to all eduGAIN core services. The database stores:
The database is placed on a host separated from the external network, accessible only trough a limited numbers of secure hosts. Database access is realised via dedicated user accounts with access right crafted to minimize the possibility of unauthorized changes.
The database is managed mostly via a web interface secured with access passwords. Modification of data on security levels S, 1, 2 (see below for explanation) can be done without any additional protection. Management of data with security level 3 is protected with on-time passwords mailed to an external mail account of the managing administrator. Management of data with security level 4 requires direct access to the database host.
For security reasons signing keys can be present only for federations which have been approved to be a member of the eduGAIN SAML Profile.
| information type | security level |
|---|---|
| federation SAML policy URL | 1 |
registration practice statement URL | 1 |
federation SAML metadata aggregate access URL | 3 |
federation metadata signing key | 4 |
| registrationAuthority attribute value | 3 |
| security level | description |
|---|---|
| S | special - delegating representatives requires contact with the federation management |
| 1 | informational, not requiring special vetting |
| 2 | important contact information (while not currently used it may be introduced in the future) |
| 3 | information of eduGAIN operational relevance, requires special care |
| 4 | crucial for eduGAIN trust, requires utmost care |
The technical details of the aggregation process are described in [eduGAIN-meta]. Here we only present the operational implementation of this process.
The aggregation, signing and publishing of the eduGAIN metadata aggregate is done on an hourly basis.
All information about the system status, federation metadata channel information, federation public keys etc. is kept in the eduGAIN database and taken from there as required within the aggregation process.
aggregation host downloads federation metadata feeds using conditional GET
if the conditional GET resulted in a download of a new metadata file, such file is passed through the local validator instance, if validation succeeds the downloaded file is used as an input for aggregator, if it fails, the previous correct feed copy is used instead
the validated metadata files are passed to a pyFF flow, see also [eduGAIN-meta] Metadata combination and collision handling
pyFF aggregates and then signs the resulting feed; currently the signing is done with key files stored at the aggregation host host
the resulting file is analysed, split into entities and used to update the edugain-db
the final output is uploaded with sftp to the technical host using a dedicated user account on the the technical host.
At 45 minutes past every hour the new copy of eduGAIN metadata aggregate is copied to the final destination directory and when the copy is completed the mv action is performed in order to substitute the production file in an atomic mode
Finally the new eduGAIN metadata aggregate file is copied to the history repository and compressed
As described in [eduGAIN-meta], under certain conditions aggregation alerts are raised. The current practice is that these alerts are sent as e-mails to the eduGAIN OT. Since alerts are relatively rare and federation metadata feeds can be cached for at least 4 days, the eduGAIN OT makes its own decision on how to react to a particular alert. Usually before sending a notification to a federation, the OT waits until the next aggregation run to make sure that the situation has not been rectified by the federation.
If the OT decides that a notification needs to be sent to the federation, the official contact address registered be the given federation is used. If one of the following conditions is met:
then the OT sends additional notifications to the federation delegate and the deputy using their e-mail addresses registered by the given federation.
If it becomes likely that a given federation may not be able to react in time and that its cached metadata feed may expire, the eduGAIN OT sends a warning to the eduGAIN SG mailing list.
It must be realised that that the case of all entities supplied by a large federation being deleted from eduGAIN has heavy consequences - other participating federations will naturally have to drop these entities. When the federation metadata feed becomes available again, other federations may be forced into running emergency regeneration of their metadata, service providers may observe limited breaks in their service. Therefore the eduGAIN OT is making all possible effort to avoid such situations. If the eduGAIN OT realises a very special situation it is allowed to temporarily stop aggregation in order to avoid the deletion of of the federation but it MUST immediately notify the eduGAIN SG that such measures have been taken.
One example of such a special situation may be a real case of an introduction of a valid but a very short-lived metadata file followed by a metadata error causing a aggregation reject. That situation, leaving no time for normal procedures to take place, was caused by a configuration error on the federation side and was rectified in a short time while the eduGAIN aggregation was suspended.
Metadata requirements have direct operational impact. a violation of the requirements results in rejection of a federation feed. The requirements as understood in this documents are the rejection rules implemented in the eduGAIN metadata validator and automatically applied in the aggregation process.
As a principle requirements for federation feeds must be based on either general standards to which eduGAIN SAML profile adheres or on the eduGAIN SAML profile. In the case of standards, the experience shows that certain violations are only discovered when reported by participating federations - not all such violations are reported by standard schema validation tools, and in fact not all are just schema errors. Whenever a new problem is reported, the OT makes an assessment whether it in fact violates a required standard and if so then:
Every rule is documented in the [eduGAIN-meta] .
When raising an error, the validator points to the specific rule in [eduGAIN-meta].
As already mentioned above, there may be cases where an immediate OT intervention is required and
Additions to metadata best current practices need to be decided by the eduGAIN SG. Each such good practice needs to be implemented as an eduGAIN validator warning by the eduGAIN OT. Each good practice rule needs to be added to [eduGAIN-BCP].
In the case of an unexpected problem resulting from metadtata aggregation (which may result from an unusual error on a federation side or some software bug in one of the aggregation process steps) the eduGAIN OT has access to hourly copies reaching 24 hours back and to several years of daily copies .
Restoration of snapshots or full virtual machines is possible (and has been performed several times not as disaster recovery but in order to get access to some old files for statistics reasons).