Introduction

This page contains information for federations that wish to join eduGAIN. This guide therefore is primarily aimed at operators of academic identity federations, in particular the technical staff members of a federation operator.

This page is structured in distinct steps that are aligned with the eduGAIN joining process. It assists federations to produce all the required information for each step in order to streamline the process for both the joining federations as well as the eduGAIN Operations Team. In addition this page provides best practices, recommendations and implementation options that have proven to work well for other eduGAIN member federations.

Prerequisites

Before actually starting the joining procedure, please ensure that the following prerequisites are given.

Check Requirements

Please read and understand the requirements that your federation meet to join eduGAIN. The requirements are summarized below:

...

If you are unsure whether your federation meets these requirements or if you need more information about the requirements, please contact edugain@geant.org.

Opt-In vs Opt-out

Before joining eduGAIN you might want to consider how the entities (Identity and Service Providers) in your federation can join eduGAIN. Adding all of them to eduGAIN might not be reasonable as some of them are certainly used only locally (e.g. federated services used only by users of a single university) and therefore do not have to be part of eduGAIN.

There are basically two choices how entities can be added to eduGAIN from a federation’s point of view:

Opt-In

In this model each Service Provider (SP) and Identity Provider (IdP) of a federation has to do something to get included in eduGAIN. Depending on your federation, this might include:

...

The disadvantage is that opt-in does not scale very well for many entities and it generally takes longer because SP and IdP administrators actively have to do/change something in order to join eduGAIN, which could take years. To motivate entities to get eduGAIN-enabled needs also quite some marketing efforts to make them aware of eduGAIN and to highlight the advantages of taking this step. Especially the latter point is difficult because for the people running an Identity Provider the advantages of becoming interfederation-enabled is less obvious. The IdP administrators sometimes rather see the risks (data privacy, personal data of users sent to services abroad/in another federation) and additional work than the advantages that their users (especially researchers) benefit from.

Opt-Out

Compared to the opt-in model, your SP and IdP administrators in the opt-out model don’t have to do anything specifically (legal or technical) to be exposed to eduGAIN. Typically this only works if the federation policy already allows the federation operator to use this model when becoming an eduGAIN member federation.

...

Before applying the opt-out model, it is recommended to leave administrators of the affected entities several weeks time to opt-out before their entity is published to eduGAIN. It also might make sense from a federation operator’s point of view to remind some entities specifically to consider an opt-out. This is especially true for SPs that are used internally only or for IdPs whose users are very unlikely to access eduGAIN services.

What kind of federations have adopted opt-in or opt-out?

An overview of which federation has chose which model is available on the Metadata Upstream/Downstream page. Practice has shown that federations who have a comprehensive and protective local policy framework in place tend to be inclined to take an opt-in model, because

...

There are also federations that do not have comprehensive local policy and focus mainly on the technical infrastructure (reliable SAML2 metadata exchange and delivery). For them, adopting an opt-out model is more straightforward.

Recommendation: IdP Opt-Out, SP Opt-In

In the recent years, more and more federations (e.g in Sweden, France, Italy) have decided to move from an opt-in model to an opt-out model. The opt-out model can be implemented for IdPs only or both, IdPs and SPs. For operators of eduGAIN services it is important that many organisations and their users can log in via eduGAIN. Having many Identity Providers in eduGAIN is therefore preferable. On the other hand, only services should be accessible via eduGAIN that also are configured properly to be accessed via eduGAIN. Therefore, a good choice is to use the opt-out model for IdPs and an opt-in model for SPs.

...

-- Olivier Salaün from RENATER, the federation operator for France

Read the eduGAIN Policy

Federations willing to join eduGAIN should read, understand and accept the eduGAIN Policy documents. The eduGAIN policy consists mainly of two documents:

...

The Data protection Code of Conduct describes an approach to meet the requirements of the EU Data Protection Directive in federated identity management. The Data protection Code of Conduct defines behavioral rules for Service Providers which want to receive user attributes from the Identity Providers managed by the Home Organisations. It is expected that Home Organisations are more willing to release attributes to Service Providers who manifest conformance to the Data protection Code of Conduct.

Local Federation participants

Federations willing to join eduGAIN should already have at least one (1) participating entity Identity Provider and this should be reflected in the federation’s metadata.

Establish a secure communications channel

All email sent to the eduGAIN Operations Team for registration purposes and future updates must be signed with a personal certificate. Only certificates from CAs listed in TACAR service are accepted.

If you cannot get such a certificate to send signed emails or if your personal certificate is issued from a CA not listed in the TACAR service, please contact the eduGAIN Operations Team in order to establish a different secure communications channel.

Joining Steps

Registration of interest in joining eduGAIN

General

The first steps towards joining eduGAIN is to register the Federation’s interest in joining by communicating this to the eduGAIN Operations Team.

Contact Details

Contact details (email address, full name) for eduGAIN related matters. Please keep in mind that the assigned contacts should be available for comments and information for the whole duration of the process to join eduGAIN.

Federation Action List

Send an email message to edugain@geant.net stating the interest to join eduGAIN and containing the contact details defined above.

Expected Outcome

The eduGAIN Operations Team receives the registration of interest from the federation and works with the responsible person defined in the contact details sent in order to establish a secure communications channel.

...

In general, it is strongly recommended that the federation operator during the joining process and afterwards reacts quickly on email requests from the eduGAIN operations team or other eduGAIN members. Federations that don’t react in a timely manner on questions regarding their federation, are considered less trustworthy because in case of a security incident or another eduGAIN-realted problem, a quick reaction is essential.

Sign the eduGAIN Policy Framework Policy Declaration

General

The joining federation needs to read, understand and accept the Policy Declaration document for the eduGAIN Policy Framework.

Requirements

The Policy Declaration document for the eduGAIN Policy Framework (available on the eduGAIN documents page).

Federation Action List

A person who is authorized to represent the federation should sign the printed document and send it to the postal address of the eduGAIN Operations Team:

eduGAIN c/o GÉANT
468D Singel
1017AWLevel 6
Hoekenrode 3
1012BR Amsterdam
The Netherlands

A scanned version of the signed declaration should be sent via signed email to the following address edugain@geant.net.

Expected Outcome

eduGAIN Operations Team receives the signed Policy Declaration document from the joining Federation.

Provide the necessary Federation information

General

Now that the secure communication channel has been established between the eduGAIN Operations Team and the joining Federation, the rest of the necessary information should be exchanged.

Being an eduGAIN member federation on a technical level mostly means exchanging SAML2 metadata with eduGAIN. There are basically two metadata files exchanged between a federation operator and eduGAIN.

eduGAIN Upstream metadata

The upstream metadata contains all entities (IdPs and SPs) of a member federation that should be included in eduGAIN metadata. The upstream metadata is provided by the federation operator for consumption by the eduGAIN Metadata Distribution Service (MDS).

...

The eduGAIN Metadata Profile contains useful information what should be published about entities that you add to eduGAIN. It is strongly advised that all recommendations (“SHOULD”) are implemented. Many problems and issues around eduGAIN stem from the fact that the recommendations are not implemented. E.g. ensure for example that all Service Providers from your federation publish which attributes they request. Otherwise, they most probably won’t get any, which causes login problems for end users.

eduGAIN Downstream metadata

The eduGAIN Downstream metadata contains all entities in eduGAIN. It is generated and published by the eduGAIN Metadata Distribution Service (MDS), see https://technical.edugain.org/metadata for details.

...

Information on how to republish the eduGAIN downstream metadata can be found in Republish eduGAIN Metadata.

Metadata Signing Certificate

eduGAIN collects the metadata of all the participating federations, re-signs and publishes the aggregated metadata for the interfederation so that it can be consumed by all the participating Federations. In order to be able to validate the integrity and authenticity of the Federation’s metadata, the eduGAIN Operations Team needs to receive the certificate with which the Federation signs it’s locally aggregated metadata.

Governance Information

eduGAIN is governed by the eduGAIN Steering Group (see eduGAIN governance). Each federation should assign one delegate and at least one deputy to participate in the eduGAIN Steering Group (eSG). The eSG decides for example if a new federation is accepted as eduGAIN member or not. Therefore, there role of a delegate serves an important purpose.

Federation Online Presence

Each Federation should have an online presence with information regarding the federation structure, the participating entities, etc. It should also define an English Metadata Registration practice statement for the federation. This document must describe rules and procedures used for registering entities which get exposed to eduGAIN. Finally the policy of the Federation should be made available. The relevant documents for the existing federations, which are available here , can be consulted when authoring the Federation Policy and the Metadata Registration practice statement. The templates from REFEDS also provide an excellent starting point for your federation’s Policy and Metadata Registration Practice Statement

Requirements

• The URL where the Federation publishes its metadata.
• The signing certificate with which Federation metadata is signed.
• The full names and email addresses of the delegate and the deputy delegate of the Federation.
• The URL pointing to the website (English version, if available) of the Federation.
• The URL pointing to the English version of Metadata Registration practice statement for the federation.
• The URL pointing to the English version of the Federation’s policy.

Federation Action List

Compose the information of the items described in the requirements section above and send them via signed email to the eduGAIN Operations Team

Expected Outcome

eduGAIN Operations team checks the provided information. They verify that the Federation’s locally aggregated metadata are syntactically correct, that the provided URLs are valid and correspond to the required information. A reply is sent to the joining Federation indicating whether the information provided is correct and sufficient and requesting modifications or updates if necessary.

Finalization of the joining process

Once the joining Federation has successfully completed all the steps indicated above and eduGAIN Operations Team has received the required information, a final approval is required by the eduGAIN Steering Group (eSG). The current procedure is that five members of the eSG are chosen to examine the application of the new candidate federation. 
The members are selected alphabetically cycling through the list of existing members. In particular they will inspect metadata, the web page, the federation policy, the metadata practice statement and other aspects of your federation. They then will send recommendations and questions to the eSG mailing list. They also might ask for more information. As mentioned, it helps if you reply to questions quickly as this demonstrates that you as a federation operator are likely to also be responsive in case of security incidents or other eduGAIN-related emergency situations.

...

Finally an email notification is sent to the federation announcing the successful completion of the joining process.

Post Joining

When the federation has successfully joined eduGAIN

Disseminate information regarding eduGAIN

You can perform the following steps  to make your community aware of eduGAIN

• Write guides for your SPs and IdPs on how to make use of eduGAIN and publish them on your federation’s website. See for example the following guides:
  • SWITCH: https://www.switch.ch/aai/support/documents/interfederation/
  • RENATER: https://services.renater.fr/federation/docs/fiches/edugain
• Organize events, trainings for your community.
• Create mailing lists when eduGAIN related issues will be discussed.

Stay updated

You can perform the following steps to stay updated with the latest discussions/events:

...