This page provides a general high-level overview of the steps that are necessary for a service operator to enable his service for eduGAIN.
A more concrete guide with step-by-step instructions is provided by the page How to Join eduGAIN as Service Provider.
Requirements
Services to be enabled for eduGAIN should meet the following requirements:
- Web-based: The service should be a web application. Even though non-web profiles like the SAML ECP profile could be used in eduGAIN too, most Identity Providers in current identity federations (including) eduGAIN support web-based applications only.
- SAML Interoperabel: It is assumed that the service can be protected by a SAML Service Provider like Shibboleth or Simple SAML PHP.
General Procedure
A. Service Registration
Because eduGAIN is not a confederation (federation of federations) but an interfederation service (provides connectivity between certain entities of different federations), it contains a subset of all services in federations that joined eduGAIN. This means that in order to enable a service for eduGAIN, that service has to become part of an existing identity federation, which joined eduGAIN. This is depicted in the following graphic:
If the service is already registered in an identity federation that is part of eduGAIN, proceed to to B.
If the service is not already registered in an identity federation, register it with an existing Identity Federation that is already an eduGAIN member federation. If the organisation in whose name the service is registered is not yet member of that federation, it might be necessary to join that federations first. The processes to join a federation depends from federation to federation but it will most likely involve the organisation signing some kind of a service agreement.
B. Adapt Application to Support SAML-based Login
If the service already makes use of SAML for authentication, proceed to C. If not, continue with:
- Install a SAML Service Provider like Shibboleth or SimpleSAML PHP to protect the service.
- Adapt the application to use the SAML attributes in order to authenticate users and use their attributes (like mail, display name, unique identifier, etc.)
- Implement access control rules or some kind of group management if authorization is neeeded.
C. eduGAIN Opt-In
Most federations participating in eduGAIN expose only those entities to eduGAIN that opted-in for eduGAIN. The process to opt-in for eduGAIN depends from federations to federation. Some federations just require the service operator to tick a checkbox on the federation's management interface, others will require a signed document from the service operator or his organisation.
In most federations it is also necessary to adapt the configuration of the Service Provider in order to opt-in. Often this involves configuring another source of SAML2 metadata, which then contains the eduGAIN entities.
Please consult the documentation of the federation that the service is registered with in order to find out if and how the service can be opted-in for eduGAIN support.
D. Support the GÉANT Dataprotection Code of Conduct
The GÉANT Dataprotection Code of Conduct (page in Coco, update link) a self-declaration stating that the operator of the service will follow the data protection principles mentioned in the Code of Conduct. For services operaterated in EU/EAA and Switzerland it is strongly recommended to support the Code of Conduct because it increases the chance that Identity Provider will release all or more of the requested attributes to the service. The Code of Conduct increases the trust that an Identity Provider can have in that service when it comes to provide it with data about the user who wants to access the service.
E. Use a Discovery Service that supports Interfederation
When a service can be accessed by users from multiple organisations from multiple federations, it must be ensured that the user during the login process can find and select the organisation he wants to authenticate at. This process is called Identity Provider Discovery. There are multiple open-source implementations (Shibboleth Discovery Service, SWITCHwayf) that allow to operate an own Discovery Service. Alternatively, there are also hosted solutions (Disco Juice) that could be used instead.
Some SAML implementations like SimpleSAML PHP already include a Discovery Service that will automatically display all Identity Providers whose users might access the service.
One particular aspect to handle specifically is the case where users need to access the service who are affiliated with an organisation that:
- Is not yet part of eduGAIN
- Cannot become part of eduGAIN
In such cases, one solution might be to add a special Identity Provider that serves as a "Home for the Homeless" users. Such Identity Provider are operated by multiple federations. Often they allow user self-registration only by verifying an email address. There are however also solutions that allow an operator of a service to specifically create accounts for users that are eligible/verified to get access to the service.
F. Adapt attribute mapping and attributes Used
If the service already was operated within a particular federation before its target user group was extended to also include eduGAIN users, it might be necessary to review and adapt the attributes that the service (or its Service Provider) is able to consume and use for authentication and authorization. The attribute names and values used in some federations might be slightly different to the ones used in other federations.
G. Adapt Access Control Rules
After reviewing the attributes that are supported by the service and its Service Provider, it might also be necessary to check if the acess control rules still work. This is in particular the case for applications that perform access control based on certain attributes and their values.
H. Test Interfederation Access
Testing access to a service via eduGAIN will often require a user from another federation to access the service. This is because most federations don't allow test accounts.
How to start?
The above high level topics that are relevant for adding a service to eduGAIN are described in greater detail and extended by step-by-step instructions on the page How to Join eduGAIN as Service Provider.
Special Cases
For research groups that are likely to operate many services and potentially in different countries and federations, we recommend reading the document Options-for-Joining-eduGAIN (PDF) that illustrates the different options that apply in such cases.