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:


Page start-linking

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).
  • 'requestedAttributes' (optional): The comma-separated names of additional attributes that should be returned in the linking-confirmation URL, additionally to the swissEduID and the contact e-mail address attribute. Currently, the following additional attributes can be requested: 'swissEduPersonUniqueID'.
    The default is an empty list of additional attributes.
  • '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. Alternative equally safe algorithms are 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 eduid@switch.ch to securely exchange the secret.

Example:
HTTP GET request to linking service with sharedSecret 'B7i5zNka00eiyGm2':
https://eduid.ch/web/linking-service/?token=hF3YO5MWOBSuvVW2&swissEduPersonHomeOrganization=unidemo.ch&hmac=1605d9eec99cded505989330193e92159172b52d81cd7fe4481cfc76ea041861&requestedAttributes=swissEduPersonUniqueID

Hints:

  • 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 authenticate with a valid edu-ID account. Users without an edu-ID can create an account 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. Instead it will redirect the user immediately  to the linking-confirmation page. Along with the redirection, the HTTP GET parameters edu-ID identifiers swissEduID, the one-time token, the contact e-Mail address mail, optional requested attributes and the HMAC value are included in the URL redirecting the user to the organization's linking-confirmation page. If the linking service was called with a non-empty 'requestedAttributes' argument, all eligible requested attributes are also added to the linking-confirmation page URL.

The HMAC value is computed as follows: hmac(SHA256, token + swissEduID + mail [ + swissEduPersonUniqueID ], sharedSecret), where + is the string concatenation operator and sharedSecret is a common secred that is shared between an organization and SWITCH. The values in square brackets ('[ ]') are only used in the hmac calculations if the respective attributes were requested with the 'requestedAttributes' argument.

Hints:

  • The values are not url-encoded when calculating the hmac code.

Example:
A user is redirected to an organization linking-confirmation page with the following HTTP GET request with the sharedSecret 'B7i5zNka00eiyGm2':

https://unidemo.ch/.../linking-service/?swissEduID=0000802b-ef03-4b73-85e9-9390abf5de5c&mail=lukas.haemmerle%40switch.ch&token=hF3YO5MWOBSuvVW2&swissEduPersonUniqueID=204893698426%40test.eduid.ch&hmac=ba8284a90f2c899d40ca6edf6b936516f9b1cea552a80c45f1895d3725eef940

Return URL

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.

A complete redirection URL to the linking-confirmation page using these two parameters would look like in this example:

https://unidemo.ch/.../linking-confirm/?swissEduID=0000802b-ef03-4b73-85e9-9390abf5de5c&mail=lukas%40haemmerle.net&token=hF3YO5MWOBSuvVW2&hmac=ba6464a0e55f2bf787672e04e8144af1e4be84973b83d6e37e3003ec115fb4c9&initialFlowServiceName=SLSP+Registration&initalFlowReturnURL=https%3A%2F%2Fregistration-test.slsp.ch%2FShibboleth.sso%2FLogin%3FentityID%3Dhttps%253A%252F%252Ftest.eduid.ch%252Fidp%252Fshibboleth%26target%3D%252Fregister%252F%253Flang%253Den

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'.

Page linking-confirm

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, swissEduIDmail (plus optional requested attributes) against the provided parameter 'hmac'.

  • The parameters should only be used if the calculated HMAC value is matching the value in the parameter 'hmac'.
  • Check that the parameter 'token' is identical to the one generated before the user was redirected to the edu-ID linking service.
  • If the HMAC code and the token matches, store the edu-ID identifier swissEduID, which is received as one of the GET parameters, 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 yet 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 via the Attribute Pull interface.
  • Show the user a status message. A basic message to the user should be something like:
    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.
  • Ideally also show a button to allow the user to continue to the service, as described in the above chapter "Return URL".