Steps to integrate edu-ID at an Organization

Follow the steps below

Migration: to integrate an existing AAI IdP into the edu-ID service


start from scratch: to set up a new organization as Home Organization in the SWITCHaai identity federation with edu-ID integration.

Setting up a new organization from scratch is usually easier to do, and some of the tasks listed below can be ignored.

Purpose of an edu-ID Integration at an Organization

An edu-ID Identity can be used by any individual and member of an organization. However, for SWITCHaai-federated organizations to get all the benefits, they need to integrate the edu-ID infrastructure interfaces. Most notably this means two things:

  1. The organization does not need its own federated (AAI) IdP. This function is outsourced to the edu-ID IdP.
  2. Some of the idenitity management processes at the organization are integrated with edu-ID. For a minimal integration, the IdM processes for onboarding (registering a new member at the organization and creation of an edu-ID affiliation), offboarding (a member leaves the organization) and attribute updates (the organization changes attributes or the status of a member) are interconnected between edu-ID and the organization.

Optionally, additional organizational identity management processes may be integrated with the edu-ID service.

Required Resources

The resources required to integrate an organization in edu-ID depends in a high degree on the setup and the identity management at the organizations. Based on our experiences a very rough estimate is a workload of 10-30 days for a migration and 5-15 days for a setup from scratch.

1. Contractual Preparations

In order to act as a Home Organization in the SWITCHaai federation, the organization must either be part of the SWITCH community, or it must have signed the federation partner plus agreement.

Organizations who already operate an IdP in the SWITCHaai federation can skip this step.

2. Concept and Planning

 Elaborate an organisation-specific integration plan for SWITCH edu-ID:

  • Current status and architecture of identity management at the organization
  • Strategic goals and benfits of the organization with edu-ID
  • Identification of relevant identity management (IdM) processes, potential for improvements
  • Risks
  • Communication strategy towards students, teachers, and administrative staff
  • Choice for the technical integration approach:
    • Development of appropriate integration scenarios to onboard new members and current organizational members
    • Choice of technical protocols to update the affiliation status and exchange attribute data
  • Time and resource planning for implementation and regular operation

Typically involved stakeholders are members of central IT of the organisation who are responsible for the IdM, authentication and registration processes. If required involve also other interested parties (student administration, business applications etc.), and consultants of SWITCH.

Below is a typical example of an adoption scenario for onboarding and offboarding members. It shows how edu-ID accounts are linked (and unliked) with organizational accounts:

User group Students, continuing education
Onboarding of new members. Linking and creation of an affiliation.

Linking-at-registration: Via online registration (registration with edu-ID); Transfer of identifier from administration tool to IdM.

Creation of an affiliation via the Affiliation-API after successful admission.

Linking-after-admission: An internal account is created for new staff members. They are invited to link their edu-ID to the internal account on the organizational linking service.

Creation of an affiliation immediately after completion of linking service via the Affiliation-API.

Linking of current  members and creation of an affiliation.

Linking-after-admission: Linking via organizational linking service.

Immediate creation of an affiliation via the Affiliation-API.

Updating and removing affiliations (offboarding)

Attribute updates sent by university IdM to edu-ID with Affiliation-API.



3. Technical Implementation

A technical specification is derived from the adoption concept, which can then be implemented and tested. The specification and implementation phase may overlap the preparation of the user transition phase.

The required building blocks below strongly depend on the selected adoption concept.

3.1. Get Checklist

SWITCH has prepared three checklist templates that can be customized by each organization

  • List of technical tasks to be completed by SWITCH and/or the organization (generic template)
  • List of attibutes to be supported by the organization (generic template)
  • (Optional) List of critical SPs that are to be tested using the edu-ID staging IdP (generic template)

Note that the checklists contain all the necessary tasks for an organization that migrates an existing AAI-Idp to edu-ID. Organizations who set up a new home organization from scratch only need to complete a subset of these tasks.

3.2. Implement Linking Service to onboard organizational Members

Implement one or more local web applications to get the edu-ID identifier for the members of an organization.

a) Choose the best hook to add account linking in the organizational IdM process (at least one of the following):

b) Choose an implementation method:

The organizational linking service is generally required, while the edu-ID registration page is optional.

3.3. Implement Attribute Synchronization

Affiliations - including their attributes - are synchronized from the organization to edu-ID. Implement the attribute push method which is strongly preferred. In special cases the alternative attribute pull method may me chosen if mutually agreed.

3.4. Automatic Account Reconciliation (optional)

Administrators of home organizations in the federation will receive an automated email message if one of their members has merged two accounts requiring an update in the local user directory. This process may be automated by using the bulk check function of the tools API.

3.4. Testing

Testing and deployment of implementations together with SWITCH:

  • Linking Service: Check that the organization gets the correct edu-ID Identifier
  • Attribute synchronisation:
    • Make sure that all attributes are properly synchronized to edu-ID via GET on the Affiliation-API or by checking the affiliations in the Administration Portal
    • Make sure that affiliations are also correctly updated and removed
  • (Optional) Log into services or the attribute viewer via the regular edu-ID IdP, the test IdP and/or the staging IdP

Consult the Testing Instructions for further information.

4. Communication

4.1 Set up an edu-ID Information Page

Set up a web page with organization specific aspects of the edu-ID integration.

  • The page is preferrably public
  • Should be understandable for common organization members (students, staff, teachers etc.)
  • Describes the basic concept of edu-ID: a user-centric identity that is used during and after studies to access various academic services
  • Describes the organizational linking process
  • Info about the login process like choose your organization in the WAYF
  • May make recommendations like how to secure the edu-ID account
  • Where to get help

Some public examples of such pages: FHNW, HEP Vaud, PHBern, PH GraubündenUni Basel, Uni Bern, Uni Fribourg, Uni Genève, Uni Lausanne, Uni Luzern, Uni St. Gallen.

4.2 Communication towards Services

edu-ID is fully backwards compatible with an organizational AAI-IdP. Therefore, when migrating from AAI to edu-ID no technical adaptations are required for an SP, if it is properly configured as recommended.

It is still a good idea to inform the most important SPs when an organizational IdP is migrated to edu-ID. For an SP operator it may be advisable to test edu-ID compatibility before the migration or to adapt login buttons to make the support for edu-ID explicit.

4.3 Communication towards Users

In this phase the organization members are moved from the organizational AAI account to SWITCH edu-ID.

  • Inform current members of the imminent change applied to their federated identity
  • Members who do not already have an edu-ID account need to create one on their own
  • Members who have an edu-ID account without organizational affiliation need to go through one of the linking services to add an affiliation.
  • Inform users about login process(es) and credentials to be used
  • Adapt support processes and provide help

SWITCH can provide example texts on request.

5. Preparations for regular Operation

5.1 User support

SWITCH provides end-user support for cases like lost passwords, lost access to 2-step login and other general questions.

The organization provides end user support for questions and issues related to the linking service and attribute synchronization.

Contact information should be exchanged between the organizational support and SWITCH support.

5.2 Account reconciliation

HomeOrg Administratos may occasionally be notified when edu-ID accounts were merged. In such cases the edu-ID Identifier of a person may change, and need to be updated in the local database.

This process my optionally be automated. With the account reconciliation API an organization can regularly check if edu-ID accounts have been merged.

5.3 System maintenance

Maintenance of edu-ID linking service and attribute synchronization.

Contact information should be exchanged between the organizational unit or IT-staff in charge of these components and SWITCH technical support.

5.4 Stay tuned about edu-ID

We recommend recommended to

  • regularly read the identity blog
  • subscribe to the edu-ID newsletter with general news about edu-ID (about 4 newsletters per year)
  • subscribe to the edu-ID operations mailing list with important technical/operational information for sysadmins