Date: Fri, 29 Mar 2024 15:02:51 +0000 (UTC) Message-ID: <790345030.6172.1711724571544@fra-prod-wiki01.geant.org> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_6171_1109853815.1711724571541" ------=_Part_6171_1109853815.1711724571541 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html
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 ope= rator.
This page is structured in distinct steps that are aligned with the = ;eduGAIN joining process. It assists fede= rations to produce all the required information for each step in order to s= treamline the process for both the joining federations as well as the eduGA= IN Operations Team. In addition this page provides best practices, recommen= dations and implementation options that have proven to work well for other = eduGAIN member federations.
Before actually starting the joining procedure, please ensure that the f= ollowing prerequisites are given.
Please read and understand the requirements that your federation meet to= join eduGAIN. The requirements are summarized below:
Participant Federations MUST:
If you are unsure whether your federation meets these requirements or if= you need more information about the requirements, please contact e= dugain@geant.org.
Before joining eduGAIN you might want to consider how the entities (Iden= tity 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 u= sed only locally (e.g. federated services used only by users of a single un= iversity) and therefore do not have to be part of eduGAIN.
There are basically two choices how entities can be added to eduGAIN fro= m a federation=E2=80=99s point of view:
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 y= our federation, this might include:
Organisations first have to sign a special interfederation/eduGAIN polic= y document. This might be necessary because your existing federation policy= does not yet cover the case where your SPs and IdPs would be interfederate= d, thus communicate with SPs and IdPs from other federations abroad.
SPs and IdPs have to apply configuration changes. This can include:
The advantage of opt-in is that only those entities are exposed that are re=
ally to interoperate with other entities from other federations. For some e=
ntities, it might not make sense to be part of eduGAIN. Examples of such en=
tities are
Such entities might not want to opt-in, therefore they don=E2=80=99t have t=
o take any steps.
The disadvantage is that opt-in does not scale very well for many entiti= es and it generally takes longer because SP and IdP administrators actively= have to do/change something in order to join eduGAIN, which could take yea= rs. To motivate entities to get eduGAIN-enabled needs also quite some marke= ting efforts to make them aware of eduGAIN and to highlight the advantages = of taking this step. Especially the latter point is difficult because for t= he people running an Identity Provider the advantages of becoming interfede= ration-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 use= rs (especially researchers) benefit from.
Compared to the opt-in model, your SP and IdP administrators in the opt-= out model don=E2=80=99t have to do anything specifically (legal or technica= l) to be exposed to eduGAIN. Typically this only works if the federation po= licy already allows the federation operator to use this model when becoming= an eduGAIN member federation.
To use this model, there are a few conditions that have to be met before= taking this step:
If Opt-out is also chosen for SPs, you also have to be aware that your c= entral Discovery Service might have to be adapted to also show eduGAIN Iden= tity Providers.
The advantage of this model is that it saves work for everybody involved. T=
he federation operator because he can accelerate the eduGAIN-adoption consi=
derably without much marketing efforts (the federation participants should =
though be clearly informed about this step and its consequences). The admin=
istrators of affected entities generally don=E2=80=99t have to do much. Wha=
t they can and in some cases should do is:
The disadvantage of this approach is that the federation operator needs ini=
tially to do more work to carefully plan this move. What happens otherwise =
is that entities are exposed to eduGAIN which are not really ready for eduG=
AIN. Be it that they don=E2=80=99t load/update metadata containing other ed=
uGAIN entities, be it that their access control rules are too wide, be it t=
hat attribute release is not configured well and thus users cannot really a=
ccess eduGAIN services. All of these cases deteriorate not only usability a=
nd reputation of eduGAIN but also that of the local federation. Therefore, =
this should be avoided if possible.
Before applying the opt-out model, it is recommended to leave administra= tors of the affected entities several weeks time to opt-out before their en= tity is published to eduGAIN. It also might make sense from a federation op= erator=E2=80=99s point of view to remind some entities specifically to cons= ider an opt-out. This is especially true for SPs that are used internally o= nly or for IdPs whose users are very unlikely to access eduGAIN services.= p>
An overview of which federation has chose which model is available on th= e Metadata Upstream/Downstream page. Practice has shown that federa= tions who have a comprehensive and protective local policy framework in pla= ce 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 excha=
nge and delivery). For them, adopting an opt-out model is more straightforw=
ard.
In the recent years, more and more federations (e.g in Sweden, France, I= taly) have decided to move from an opt-in model to an opt-out model. The op= t-out model can be implemented for IdPs only or both, IdPs and SPs. For ope= rators of eduGAIN services it is important that many organisations and thei= r users can log in via eduGAIN. Having many Identity Providers in eduGAIN i= s therefore preferable. On the other hand, only services should be accessib= le 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.
Also have a look at the section eduGAIN Upstream metadata&= nbsp;on how to best handle eduGAIN upstream and downstream metadata that is= affected by the opt-in or opt-out choice.
"RENATER has good experience with this hybrid model (IdP Opt-out, SP Op=
t-in). It really makes sense for SPs to decide to join eduGAIN and anyway t=
hey need to use a different discovery service for eduGAIN and that's the mo=
st visible part of the eduGAIN participation iceberg. Doing Opt-out for IdP=
s really makes sense because Virtual Organisations (VO) are expected to bec=
ome the lion share of eduGAIN SPs and VO members represent only a small num=
ber of person per institution; it would be hard for VOs to convince one ins=
titution to join eduGAIN."
-- Olivier Sala=C3=BCn from RENATER, the federation operator for France<= /p>
Federations willing to join eduGAIN should read, understand and accept t= he eduGAIN Policy documents. The eduGAIN policy consists mainly of two docu= ments:
On the eduGAIN Resources page= there are four further optional profile documents available. Eve= n though they are optional, it is strongly recommended to implement these p= rofiles because they improve the interoperability with other eduGAIN entiti= es. This reduces the number of problems and thus benefits you and the users= of your federation. The profiles are summarised below:
The eduGAIN metadata profile defines rules for SAML metadata producers t= hat plan to submit their metadata to the eduGAIN Metadata Service (MDS) for= aggregation. It is based on the OASIS SAML V2.0 Metadata Interoperability = Profile Version 1.0 and intends to facilitate scalable SAML interoperabilit= y between eduGAIN participants.
This is the recommended profile for end users' attributes exchanged thro= ughout the eduGAIN service. This profile covers only the Web Single Sign-On= scenario.
eduGAIN SAML 2.0 W=
ebSSO Profile
This optional profile defines the SAML 2.0 Web Single Sign-on Protocol P= rofile for the eduGAIN Service. It currently is a pointer to the SAML2int (= link http://saml2int.org/) profile as this is the only allowed SAML= 2.0 profile to be used in eduGAIN. SAML2int is a SAML 2.0 Interoperability= Deployment Profile that defines a minimum set of bindings and rules that n= eeds to be followed by entities participating in eduGAIN with regards to wh= ich bindings should be used, which parts of the SAML messages should be sig= ned or encrypted and how, etc.
G=C3=89ANT Data Pr=
otection Code of Conduct
The Data protection Code of Conduct describes an approach to meet the re= quirements of the EU Data Protection Directive in federated identity manage= ment. The Data protection Code of Conduct defines behavioral rules for Serv= ice Providers which want to receive user attributes from the Identity Provi= ders managed by the Home Organisations. It is expected that Home Organisati= ons are more willing to release attributes to Service Providers who manifes= t conformance to the Data protection Code of Conduct.
Federations willing to join eduGAIN should already have at least one (1)= participating entity Identity Provider and this should be reflected in the= federation=E2=80=99s metadata.
All email sent to the eduGAIN Operations Team for registration purposes = and future updates must be signed with a personal certificate. Only certifi= cates from CAs listed in TACAR service are accepted= .
If you cannot get such a certificate to send signed emails or if your pe= rsonal certificate is issued from a CA not listed in the TACAR service, ple= ase contact the eduGAIN Operations Team in order = to establish a different secure communications channel.
The first steps towards joining eduGAIN is to register the Federation=E2= =80=99s interest in joining by communicating this to the eduGAIN Operations= Team.
Contact details (email address, full name) for eduGAIN related matters. = Please keep in mind that the assigned contacts should be available for comm= ents and information for the whole duration of the process to join eduGAIN.=
Send an email message to edugain@geant.net stating the = interest to join eduGAIN and containing the contact details defined above.<= /p>
The eduGAIN Operations Team receives the registration of interest from t= he federation and works with the responsible person defined in the contact = details sent in order to establish a secure communications channel.
Note:
In general, it is strongly recommended that the federation operator duri= ng the joining process and afterwards reacts quickly on email requests from= the eduGAIN operations team or other eduGAIN members. Federations that don= =E2=80=99t 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.
The joining federation needs to read, understand and accept the Policy D= eclaration document for the eduGAIN Policy Framework.
The Policy Declaration document for the eduGAIN Policy Framework (availa= ble on the eduGAIN documents page).
A person who is authorized to represent the federation should sign the p= rinted document and send it to the postal address of the eduGAIN Operations= Team:
eduGAIN c/o G=C3=89ANT Level 6
Hoekenrode 3 1012BR Amsterdam The Netherlands
A scanned version of the signed declaration should be sent via signed em= ail to the following address edugain@geant.net.
eduGAIN Operations Team receives the signed Policy Declaration document = from the joining Federation.
Now that the secure communication channel has been established between t= he eduGAIN Operations Team and the joining Federation, the rest of the nece= ssary information should be exchanged.
Being an eduGAIN member federation on a technical level mostly means exc= hanging SAML2 metadata with eduGAIN. There are basically two metadata files= exchanged between a federation operator and eduGAIN.
The upstream metadata contains all entities (IdPs and SPs) of a member f= ederation that should be included in eduGAIN metadata. The upstream metadat= a is provided by the federation operator for consumption by the eduGAIN Met= adata Distribution Service (MDS).
Most federations don=E2=80=99t publish all their entities in eduGAIN met= adata. This might have legal and technical reasons (see sections about opt-= in vs opt-out). Even if a federation chooses the opt-out model described ab= ove, this means that not all entities of that federation will be part of ed= uGAIN. Therefore, there will almost always be a separate metadata file that= is aggregated by eduGAIN MDS. This file does not have to be public on your= web page, but it certainly will be public on the eduGAIN technical page.= p>
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.
The downstream metadata is needed because you federation=E2=80=99s entit= ies that are part of eduGAIN should also consume metadata about other eduGA= IN entities. Therefore, you as federator operator should provide your entit= ies with that downstream metadata. It is strongly recommended to provide an= own version of eduGAIN metadata to your local entities and not directly ma= ke them consume from MDS. Consuming eduGAIN metadata directly from MDS is c= onsidered bad practice for several reasons. MDS was not built to serve meta= data to potentially thousands of entities. Also, you as federation operator= lose the ability to filter out eduGAIN entities that for example are not c= ompliant with your federation policy. Furthermore, this might result in con= flicts because your entities might load metadata for other eduGAIN entities= of your federation twice (once via MDS and once via your local federation= =E2=80=99s metadata).
Providing a separate eduGAIN metadata file has also the advantage that y= ou can also split metadata in two files, one for your SPs and one for your = IdPs. Given that eduGAIN metadata has grown quite large, this mitigates sca= lability issues. Federations are advised to remove their local federation= =E2=80=99s SAML entities from the eduGAIN downstream metadata in order to a= void having duplicate entity listings.
Some federations choose to integrate eduGAIN metadata directly in their = federation metadata or create two metadata streams: one containing local en= tities only and one containing local+eduGAIN entities. This is especially t= he case for federations that choose the opt-out model.
For federations that choose the opt-in model, an alternative is to provi= de separate metadata files containing entities of the local federation and = eduGAIN entities.
Information on how to republish the eduGAIN downstream metadata can be f= ound in Republish eduGAIN Metadata.
eduGAIN collects the metadata of all the participating federations, re-s= igns and publishes the aggregated metadata for the interfederation so that = it can be consumed by all the participating Federations. In order to be abl= e to validate the integrity and authenticity of the Federation=E2=80=99s me= tadata, the eduGAIN Operations Team needs to receive the certificate with w= hich the Federation signs it=E2=80=99s locally aggregated metadata.
eduGAIN is governed by the eduGAIN Steering Group (see eduGAIN governance). Each federation should assign one delegate and a= t 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 o= r not. Therefore, there role of a delegate serves an important purpose.
Each Federation should have an online presence with information regardin= g the federation structure, the participating entities, etc. It should also= define an English Metadata Registration practice statement for the federat= ion. 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 federati= ons, which are available here , can be con= sulted when authoring the Federation Policy and the Metadata Registration p= ractice statement. The templates from REFEDS also provide an excellent star= ting point for your federation=E2=80=99s Policy an= d Metadata Registration Pract= ice Statement
Compose the information of the items described in the requirements secti= on above and send them via signed email to the eduGAIN Operations Team
eduGAIN Operations team checks the provided information. They verify tha= t the Federation=E2=80=99s locally aggregated metadata are syntactically co= rrect, that the provided URLs are valid and correspond to the required info= rmation. A reply is sent to the joining Federation indicating whether the i= nformation provided is correct and sufficient and requesting modifications = or updates if necessary.
Once the joining Federation has successfully completed all the steps ind=
icated above and eduGAIN Operations Team has received the required informat=
ion, 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 existin=
g members. In particular they will inspect metadata, the web page, the fede=
ration policy, the metadata practice statement and other aspects of your fe=
deration. They then will send recommendations and questions to the eSG mail=
ing 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 federa=
tion operator are likely to also be responsive in case of security incident=
s or other eduGAIN-related emergency situations.
Finally, the eSG will vote on the application. If the vote is successful= , the eduGAIN Operations Team adds the newly joined Federation to the Metad= ata Distribution Service (MDS) production service and updates the eduGAIN p= articipant list.
Finally an email notification is sent to the federation announcing the s= uccessful completion of the joining process.
When the federation has successfully joined eduGAIN
You can perform the following steps to make your community aware o= f eduGAIN
You can perform the following steps to stay updated with the latest disc= ussions/events: