Steps to integrate edu-ID at an Organization

Follow the steps below

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

or

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 to operate 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 5-10 days for a migration with mail-based linking method, 10-30 days for a migration with push method 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)

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.

Follow these steps to become member of the SWITCHaai federation and to set up a new Home Organization.

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:
    • Linking method: Development of appropriate integration scenarios to onboard new members and current organizational members.
      Options: organizational linking service with SP (SAML or OIDC) or with token-based method.
    • Attribute synchronization: Choice of technical protocols to update the affiliation status and exchange attribute data.
      Options: attribute push or attribute pull method.
  • 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 and the organizational helpdesk. If required involve also other interested parties (student administration, internal communication, business applications etc.), and consultants of SWITCH.

The two most common and recommended technical integration approaches are:

 

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 detailed checklist (optional)

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:

  • edu-ID enabled registration page (for linking-at-registration)
  • organizational linking service - with SP (SAML or OIDC) or with token-based method (hosted and operated by organization)
  • mail-based linking (hosted an operated by SWITCH)
  • (manual linking via email for special purposes only)

Note: some of the linking methods may be mixed.

3.3. Implement Attribute Synchronization

Affiliations - including their attributes - are synchronized from the organization to edu-ID. The attribute push method  offers most flexibility. The attribute pull method however is easier to implement.

3.4. Set up Home Organization in edu-ID IdP

SWITCH will set up the IdP for the HomeOrg in edu-ID.

For organizations migrating an AAI IdP:

  • It is recommended to send the current Shibboleth IdP configuration to SWITCH to ensure compatibility.
  • The database tables for user consent and persistent identifiers must be exported from the existing IdP and imported to edu-ID. This has to be done one day before switching to edu-ID and should be tested once a few weeks before.

For new organizations starting with edu-ID: your Home Organization has already been set up in step 1. "Contractual preparations".

3.5. 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.6. Testing

Testing and deployment of implementations together with SWITCH:

  • Prerequisite: make sure administrators and testers have access to the Administration Portal
  • Linking Service:
    • check the linking the linking process. Make sure it is robust if users share a computer.
    • check the correct creation of an affiliation
  • Attribute synchronisation:
    • Make sure that all attributes are properly synchronized to edu-ID. Compare attribute values from the old IdP obtained from the attribute viewer with the values obtained via GET on the Affiliation-API or by checking the affiliations generated in the Administration Portal
    • In particular make sure that attributes that were generated by scripts in the old IdP are now correctly handled by the sync mechanism (example: urn:mace:dir:entitlement:common-lib-terms)
    • 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 or the optional staging IdP
  • If members of the organization can configure email forwarding for organizational email: make sure that email addresses originating from edu-ID are correctly forwarded, and in particular, that SPF-headers are correctly rewritten.

Consult the Testing Instructions for further information.

4. Communication

4.1 Set up an edu-ID Information Page

Note: the information page is opional of organizations using mail-based linking.

Set up a web page with organization specific aspects of the edu-ID integration. Setting up such a page is optional for an organisation, but it is helpful in many cases.

  • 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 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: FFHS, FHNW, HEP Vaud, HES-SO, PHBern, PH Graubünden, Uni Basel, Uni Bern, Uni Fribourg, Uni Genève, Uni Lausanne, Uni Luzern, Uni Neuchâtel, 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

About 1-2 months before edu-ID introduction: Information to all members

  • Inform all 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 the login process on with edu-ID and credentials to be used

About 2-3 weeks before edu-ID introduction: targeted information to members without affiliated edu-ID account

  • Reminder to add an affiliation to their edu-ID Account
  • Reminder to create an edu-ID account for those who haven't already one.
  • Reminder not to create duplicate accounts

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 may 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

Announcements

Announcements about edu-ID, like new features, roadmap planning, and other relevant information with be published on the following channels:

  • regularly read the identity blog
  • subscribe to the edu-ID newsletter with general news about edu-ID
    1. Open a mail program which sends mail from the address you want to subscribe.
    2. Send a mail to the list subscription address
      eduid-announce-join@lists.switch.ch
  • subscribe to the edu-ID operations mailing list with important technical and operational information for administrators
    1. Open a mail program which sends mail from the address you want to subscribe.
    2. Send a mail to the list subscription address
      eduid-operations-join@lists.switch.ch

Service Status and Incidents

Up to date information about the service status, incidents and announced downtimes can be found on this page

Use the subscribe function on that page to receive relevant notifications.