Implementation of EMREX

Introduction

This document is a technical description of EMREX, and documents what has to be implemented locally to connect to the EMREX network.

Each country has two roles in the EMREX network:

1. Provide the student with application(s) that allow them to fetch their results from another HEI, either in the same country or from abroad. This will later on be referred to as the EMREX Client.
2. Provide national client(s) with functionality to fetch assessments (results from courses, qualification) from the databases containing this information. This will later on be referred to as the National Contact Point (NCP).

Because EMREX is a decentralized system, there is no major component that each country can reuse. The EMREX project does provide some modules, plugins and examples that can be used and built upon, however there are a couple of issues that cannot be solved in a general way:

1. Authenticating a student. Each country has their own way of authenticating a student in their system. In Norway there is Feide and ID-porten, Finland has Haka, Sweden has Swamid and so on. Therefore, the EMREX project cannot make a complete login module and distribute this, as each country solves this in different ways.
2. Fetching results for a student. Each country/HEI has their own student information systems. Some countries have national data sources that can provide this information. Therefore, there is not one unified way of fetching results from these systems. The EMREX-system is dependent on connecting to an existing solution that can fetch results for a given student at a given HEI. The preferred solution is to build a REST service for each student information system involved, that provides ELMO formatted data.
3. Storing results for a student. Each country/HEI has their own student information systems. So there is no standard way of storing the result data the EMREX fetches into the existing student system. When the EMREX client returns a set of results for a student, these must be stored in some local system, as EMREX does not store data in itself.

Here are a couple of diagrams that can be used as reference for the rest of the page.

1. A very simple diagram of the main components of EMREX: https://confluence.csc.fi/download/attachments/50857735/ncp.png?api=v2
2. A flow chart showing how different parts of EMREX cooperate: https://confluence.csc.fi/download/attachments/50857578/DataFlow.pdf?api=v2

So there are 5 main parts that will be referred to through this document:

1. Common components of EMREX (no local work required)
   1. SMP: Student Mobility Plugin. This is a plugin that the EMREX client uses to enable the communication with a NCP, and to ensure that the communication with the NCP is done in a standardized way.
   2. EMREG: This is a central registry the EMREX uses to fetch the data that is needed to complete the result transfer. This is also the only centralized component in the EMREX system.
2. EMREX client: This is the web application that the student uses to initiate the transfer of their results from another country. (Some local work required, could be integrated into the HEI SIS, i.e. work needed by the HEI)
3. NCP: National Contact Point. This is the point that the EMREX client contacts to fetch results. (Some local work required)
   1. Result Services: These are the services that are used by the NCP to fetch the results for the student. If you have an existing system that handles this, the NCP can simply connect to this. However, if none exist, there may be a major job to implement this. (Potentially much local work required)

Common components

To simplify the local implementation of EMREX, a number of common services have been developed.

Open source

All common code for the EMREX project is Open Source. All code is public accessible, and anybody can contribute to the coding. Code that is checked in needs to be approved before this becomes a part of the common EMREX code.

Detailed information about how to get the common EMREX code, and how to contribute.

The Student Mobility plug-in (SMP)

The SMP is the common component of the EMREX client, providing a number of REST services. This enable the HEIs to develop EMREX clients with a minimum of effort.

Detailed information about the SMP

The EMREX Registry (EMREG)

EMREG is the only common service in the EMREX network, and contains information about each NCP. The communication with EMREG is done via the SMP.

Detailed information about EMREG

Security requirements

The information exchanged in the EMREX network is personal. The whole solution must therefore secure the integrity and confidentiality in the data exchange. Confidentiality is ensured by enforcing https during transfer of results. Data integrity is ensured by adding a digital signature to the transferred results, which can be verified by the EMREX client.

SMP and NCP

SMP sends the browser to Finnish NCP (URL from EMREG) with a request to retrieve student data. The student has to log in at the NCP and consent to having the data delivered back to the client. This is what prevents hackers from retrieving student data. Results will be delivered to a URL given by the SMP in the request. The URL is not verified/authenticated, but can be displayed to the user before he/she consents to data transfer.The results are signed by the NCP. SMP receives results from the NCP. The signature is verified by the SMP using the public key retrieved from EMREG.  This ensures the data are from the real NCP. The results are encrypted with HTTPS.

NCP must

• not accept a callback URL that is not HTTPS
• display result data and where it will be delivered and ask for the user's consent before data is transferred 

EMREG

SMP fetches list of NCPs from EMREG. This happens using an HTTPS URL, with HTTPS making sure we get authentic data (EMREG server is authentic and data is not modified in transit). The information can be considered public and there is no need to authenticate the client. 

EMREG will only accept NCP-URLs that use HTTPS.

The result service

Secure implementation of the result service and secure communication between NCP and result service are the responsibility of each respective country. 

The EMREX client

An EMREX client is a (part of a) web application at a HEI, where the student can collect results from other institutions.

The EMREX project will be implementing an example EMREX client that will include the following:

1. A graphical user interface for selecting and connecting to the NCP
2. A graphical user interface for displaying the result data that has been returned from the NCP
3. Written in Java and with an English user interface

However, the EMREX project cannot implement the following:

1. A login solution. When the student access the EMREX client, the EMREX client must provide an appropriate way to log in in order to authenticate the student.
2. A solution for storing the results. When the NCP returns results to the EMREX client, the EMREX client must provide a solution for storing these results locally.

How to develop an EMREX client - step-by-step

The National Contact Point (NCP)

For each county, one or more NCPs must be developed.

The EMREX project will be implementing one or more examples of the NCP that will include the following:

1. Code that receives and interprets the request from an EMREX client 
2. A graphical user interface for displaying and selecting results that the student wants to return to the EMREX client
3. Code that sends the selected results back to the EMREX client, digitally signed.

However, the EMREX project cannot implement the following for other countries:

1. A login solution. When the student access the NCP, the NCP must provide an appropriate way to log in in order to authenticate the student.
2. Fetching data from the Result Service. The Result Service will be described below.

The Result Service

The Result Service is tasked with gathering results from the HEI that the student attended. When a student is forwarded from the EMREX client to the NCP, the NCP must facilitate the gathering of results for the student before it can be returned. This whole solution must be implemented by each respective country. Here are a couple of suggestions:

1. A national web service. It might be possible to provide a national web service that can contact each HEI with the student's ID and check whether there are are any results present. If there are any, these are gathered in a report that is delivered back to the NCP when the web service is done asking every HEI. This solution depends on the web service's ability to contact each HEI. This can be done in two ways:
   1. Direct access to the HEI database.
   2. Access via a local web service.
2. A national database. Some countries might have a national database where all results are reported. In that case, fetching of results will be solved easily with a web service that can contact this database.
3. Distributed web service. Maybe the country has several student systems and databases. If this is the case then each HEI must be contacted separately. This can be solved by giving the NCP a registry of all HEIs and their web service URLs. So the student must in the NCP select the desired HEI that they want to fetch their results from.

To re-iterate: The Result Service must be implemented by the countries themselves. In some countries this is an easier job than other places, but it is something that the EMREX project cannot solve as it is out of our scope.

Implementation details for NCP