Migration to Integrated edu-ID

The changeover from a traditional organisational AAI IdP to an integrated edu-ID IdP is a critical moment. In order to ensure a high quality of the process the following guidelines apply:

  1. Integrating the edu-ID at a university requires thorough planning and preparation. Switch should be contacted 3 to 6 months before the changeover to edu-ID.
  2. Adoption dates have to be mutually confirmed by Switch and the adopting organization. The confirmation for a time slot depend on the availablity of Switch staff. As a rule of thumb, Switch can migrate no more than one university per month.
  3. In order to allow sufficient time for preparations, the following work must be completed one month before the changeover:
    • Development of the linking method
    • Successful test of the linking service
    • Development of attribute synchronization (push or pull)
    • Successful test of attribute synchronization (all attributes required for AAI/edu-ID are synchronized correctly)
    • Documentation and communication material are ready

Statistics on usage of services on IdP

To identify important services, and services possibly not supporting a clean migration to the edu-ID, usage statistics on the organisation's IdP may help.

We recommend to create usage statistics of a period of three months. This should give a good overview about important services.

To create usage statistics, proceed as follows:

  • Download the tool loganalysis.py from https://gitlab.com/peter-/shib-idp-auditlog.
  • Copy the file "loganalysis.py" to your IdP server.
  • Run the tool against the audit files of your IdP.

    Example:
    python loganalysis.py --rploginssort /opt/shibboleth-idp/logs/idp-audit-2019-{10,11,12}*

    This will create statistics for the period October to December 2019.

If you can't run the tool directly on your IdP server, you may copy the selected audit log files to your workstation and run the tool there.

Service Transition from AAI to edu-ID

The introduction of Switch edu-ID brings some fundamental changes:

  • organizational IdPs are combined into one single IdP, and
  • users manage their own personal identity.

On the other hand, everything else remains unchanged like the basic architecture of the federation and the way how services are operated.

Bear in mind this guiding principle:

It's not the SPs that are switched to edu-ID, it's the IdP!

Don't panic – 99% of the services are not affected

Day-X is the moment when an organization switches off its own IdP and edu-ID takes over its function. Here's what remains the same before and after day-X:

  • After clicking the login button, the WAYF (list of organizations) appears
  • The user chooses the organization from the list (and not edu-ID)
  • The service gets exactly the same SAML assertion from the edu-ID IdP, with the same attribute values
  • Also direct login URLs continue to work without change

Consequently, a service does not have to change its configuration when an organisation switches to edu-ID.

The only change is what a user experiences when he/she accesses a service. When a user has selected the organisation in the WAYF

  • the user gets the login window of the organization - before day-x
  • the user gets the edu-ID login window - after day-x

How is it possible that a service operator does not have to do anything to switch from the organizational IdP to edu-ID? The answer lies in the fact that a properly configured SP regularly updates the federation metadata. On day-X the service location of an organizational IdP is updated by Switch so that it points to edu-ID platform. Usually within one hour, all SPs in the federation have reloaded the new metadata and they will direct users to the correct IdP.

Aspects to consider

Here are some aspects that should be checked for an SP which is accessed by users from an organization with edu-ID integration.

  • Make sure that the SP is properly configured, in particular that it automatically reloads the federation metadata once per hour.
  • Some login buttons at SPs are labelled "AAI Login". This is technically correct, also for users who have an edu-ID. However, in the transition phase around day-x the organization's communication will often tell people to "create an edu-ID account" and use it henceforth. To avoid confusion for users, it might be a good idea to rename a login button to "AAI / edu-ID Login". Check the design guideline.
  • SP operators and their helpdeks should be informed when day-X takes place. They should identify login problems and redirect users to the organizational helpdesk or to Switch edu-ID support.
  • Some SPs embed the AAI login window in an iframe. This is bad practice from a security perspective and has therefore been disabled in edu-ID. A good alternative is to embed the discovery service/WAYF in the SP
  • An SP has to be SAML 2 compliant according to the saml2int profile.

Testing

Testing if an SP will still work after day-x is a bit tricky.

Before day-x, an SP can be accessed from an edu-ID account only with the personal identity, but not as member of an organization. In other words, before day-x, the IdP cannot use an affiliation identity to identify a person as a member of an organization towards the SP. This is also why an organization typically cannot gradually move from AAI to edu-ID by switching one SP after the other from AAI to edu-ID over a longer period of time.

To test an SP with edu-ID before day-X, Switch can set up a staging IdP. In this scenario, selected users (who have to tweak their /etc/hosts file) can access a production SP with a production edu-ID account which is linked to a production organizational affiliation before day-X.

And the remaining 1% that is affected?

All that we said above applies to services using the affiliation attribute model – which is the compatibility mode of Switch edu-ID with traditional AAI IdPs. However, Switch edu-ID introduces many new features like the extended attribute model. To use some of the new features, an SP can change the implementation and configuration. The Switch edu-ID team happily supports SP developers and operators.

If an SP is not fully compliant with SAML or the Switch edu-ID federation, adjustments will be required. One possible solution approach might be a proxy. Please contact the edu-ID team in such cases.