SWITCH Linking Service with token
This is a description of a SWITCH linking service with token.
To set up an organizational linking service an organization needs to implement two web pages:
This page is hosted by the organisation. It is accessible only for users with a valid intranet session of the organization.
Because the user is authenticated and thus identified, the page checks if the user has previously linked the intranet account with an edu-ID account. This is done by looking up the user in the local user directory and checking if the edu-ID identifier (swissEduID) is known for that person.
If the edu-ID identifier is known, the user is informed that the linking has been done already. The basic message for the user is:
You have previously linked your edu-ID account to your university account. No further action is required.
In the future when asked during the login process to pick an organisation, select <your organisation> from the list of organisations and log in with your edu-ID password.
If the edu-ID identifier is not yet known, the user is asked to initiate the linking process. The basic message is:
In order to access csome services you need your SWITCH edu-ID account to be connected to your university account. By clicking 'Continue' you will be asked to log in with your SWITCH edu-ID account. If you don't have a SWITCH edu-ID account yet, you can create one one the fly.
'Continue'. (link to edu-ID linking service on https://eduid.ch/web/linking-service/ or on https://test.eduid.ch/web/linking-service/)
The link to the edu-ID linking service must include the following HTTP GET parameters:
- 'token': A one-time token generated by the organization. The one-time token should be a random string with at least 16 characters and it should have a limited life-time (about 15 to 60 minutes).
- 'swissEduPersonHomeOrganization': The value of the home organisation AAI attribute (i.e. the domain name of the organisation).
- 'hmac': A message authentication code to ensure the message integrity.
The hmac value must be calculated as HMAC code as hmac(SHA256, token + swissEduPersonHomeOrganization, sharedSecret), where the + sign is the string concatenation operator. Ideally, SHA256 should be used as hashing algorithm (other at minimum equally safe algorithms are however also supported on request). The sharedSecret required to generate the HMAC code must be shared between the organisation and SWITCH. Please get in touch with firstname.lastname@example.org to securely exchange the secret.
HTTP GET request to linking service with sharedSecret 'B7i5zNka00eiyGm2':
- To avoid problems of users sharing the same computer/browser the page linking-start page should enforce re-authentication for each access (= disable SSO).
edu-ID Linking Service
This page is hosted by SWITCH. It forces a user to log in with a valid edu-ID account. Users without an edu-ID can create one on the fly. Users with an authenticated session, will be forced to re-authenticate to avoid problems of users sharing the same web browser.
The linking service page will not show any content to the authenticated edu-ID user but return her directly back to the linking-confirmation page. Along with the redirection, the HTTP GET parameters edu-ID identifiers swissEduID, the one-time token, the primary e-Mail address mail and the hmac are sent to the organization's linking-confirmation page.
The hmac is built as follows: hmac(SHA256, token + swissEduID + mail, sharedSecret), where + is the string concatenation operator and sharedSecret is a common secred that is shared between one organization and SWITCH. The e-mail is not url-encoded when calculating the hmac code.
A user will be redirected to an organization linking-confirmation page with the following HTTP GET request with the sharedSecret 'B7i5zNka00eiyGm2':
This page is hosted by the organization and it should be only accessible if the user has a SWITCH edu-ID account. If accessed via the edu-ID Linking Service, this page receives a number of HTTP GET parameters.
This page should verify the GET parameters token, swissEduID, mail against the provided parameter hmac. The parameters should only be used if the calculated HMAC is matching the parameter hmac. Also, this page should check that the parameter token is identical to the one generated before the user was redirected to the edu-ID linking service. If this is the case, the edu-ID identifier swissEduID, which is received as one of the GET parameters, should be stored in the local user directory for the given user.
At this point the organization knows the edu-ID identifier of the user but edu-ID does not yet know (for sure) that the user has an affiliation with the organisation. Therefore, finally complete the bidirectional linking by creating an affiliation in the affiliation API (attribute push) or by listing the affiliation (depending on the organization's IdM process this step may be optional).
The basic message to the user on this page is:
You have sucessfully completed the linking of your edu-ID to your university account. In the future when asked during the login, select your organisation from the list and log in with your edu-ID password.
It may happen that a user is in the process of acessing a SAML service (e.g. http://registration.slsp.ch/) and may need to create an edu-ID account. If in this process the non-aai linking process is used, the user will end up not on the service that initially was accessed but on the organization's linking confirmation page (read above). The normally process stops there and the user might be confused because initially he wanted to access a service and not create an edu-ID account and linking it to an organisation account.
To prevent this situation, the user is sent to the linking-confirmation page with the optional GET parameters initialFlowServiceName (contains the service name, e.g. "SLSP Registration") and initalFlowReturnURL (contains a URL that the user can be sent to return to the initially accessed service). The values of both GET parameters are url-encoded and they are not used go generate the hmac value.
So, the complete redirection URL to the linking-confirmation page would look like in an example:
The linking confirmation page then should display a success message like described above and it should ask the user if he wants to proceed to the service whose name is mentioned in the GET parameter initialFlowServiceName.