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:
- The organization does not need its own federated (AAI) IdP. This function is outsourced to the edu-ID IdP.
- 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.
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
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
- 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 of current members and creation of an affiliation.
|Updating and removing affiliations (offboarding)
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):
- Extension of existing and development of new registration forms (linking at registration)
- Add account linking service (linking after admission)
b) Choose an implementation method:
- edu-ID enabled registration page (for linking-at-registration)
- organizational linking service - with SAML SP or with token-based method
- (manual linking via email for special purposes only)
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.
Testing and deployment of implementations together with SWITCH:
- Linking Service: Check that the organization gets the correct edu-ID Identifier
- Attribute synchronisation:
- (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.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
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