This page describes the functional flow and is provided to assist the design of merchant workflows in implementing the InAcademia academic validation service.
In the following diagram, light blue represents the merchant web shop, grey blue is InAcademia functionality. Institutional Identity Provider is represented in Green.
The figure presents the 'happy' flow, ending in a successful validation, as displayed in green, as well the possible error scenarios represented in red or orange. The error situation where a institutional IdP, or the merchant redirect URL component cannot be reached because of network issues or similar is not take into account as that is out of scope and control for InAcademia and will always yield an some error in the users browser. The InAcademia service is part of a continuing development programme and additional features planned for the future are also captured below.
There are scenarios in which merchants need to build error handling into their workflows. This table describes the scenarios and suggests mitigation. This information supplements that available in https://github.com/InAcademia/OIDC-implementation/.
Please note that InAcademia offers a test suite to assist merchants in testing its proposed workflows.
| Error | Description | Mitigation/Solution |
|---|---|---|
| Invalid Requests | When a merchant requests validation (user presses InAcademia button) the request is validated again technical correctness, as well as if it matches known configuration. See https://github.com/InAcademia/OIDC-implementation/wiki#transaction-fail for more details. If either fails, InAcademia will return an error, of either type "invalid_scope" or "unsupported_response_type". | InAcademia returns an error in conformance with the OIDC standard. It is expected the client has sufficient support to display the error and inform the end user in a useful way. The Merchant should configure appropriately crafted error messages to the user and should utilise the InAcademia test suite to validate all good and error scenarios. |
| idp_hinting not available | When a merchant implements idp_hinting it removes the need for the user to select its institution from WAYF and instead presents the Institutional login page. | If idp_hinting fails, the WAYF is presented by the InAcademia service as a standard fallback. |
| IdP not available | InAcademia presents the user with a WAYF to allow selection of the IdP. The IdP might not be available in the list (so the IdP is not in eduGAIN). | From a technical point of view there is nothing that can be done inside InAcademia or the eduGAIN landscape to allow the authentication to continue. The most appropriate mitigation is to implement idp_hinting. |
| InAcademia is not available to the IdP | The IdP is available, but technically not allowing InAcademia to authenticate or the user abandons the login. | If authentication fails, some IdPs stop the transaction. There are three potential error scenarios here: Scenario 1– the IdP isn't available in the list or isn't functioning but hasn’t implemented SAML correctly and the process will just end as there is nowhere to go. From a technical point of view there is nothing that can be done inside InAcademia or the eduGAIN landscape to allow the authentication to continue. This is a challenging scenario to resolve as the user (browser) is already at the IdP, but InAcademia does not receive a response from the IdP. We can therefore not present information on the side of InAcademia. Possible mitigation is to monitor for outgoing SAML authN request and incoming AuthN SAML responses. Normally these should match, however in this specific scenario, there will not be a response to our request. Scenario 2 – the IdP is technically unavailable, but has implemented SAML correctly and presents an authentication failed error. Merchants are advised to build in their own error handing workflow to mitigate these scenarios. |
| Authentication Fails | The IdP is available but, for some reason the authentication fails. Might be the user is not able to authenticate (password lost), OR the institution did not provide enough information to the InAcademia service to validate the affiliation (basically it is not releasing the affiliation attribute. | From a technical point of view there is nothing that can be done inside InAcademia or the eduGAIN landscape to allow the authentication to continue. However, this should be signaled from the IdP with a SAML message "Access denied". InAcademia will pick up such message and send an OIDC complient "access_denied"message to the client (the merchant). It is expected the client has sufficient support to display the error and inform the enduser in a useful way. The Merchant should configure appropriately crafted error messages to the user and should utilise the InAcademia test suite to validate all good and error scenarios. |
| Validation Failed | Technically speaking this is not an error, as this is just a possible outcome of the validation process. 3 things may lead to failure of validation: 1) the user could not authenticate (see "Authentication Fails") 2) the user has the wrong affiliation 3) the end-user did not give consent to release the necessary information | In accordance with OIDC specification an "access_denied" message to the client (the merchant), see https://github.com/InAcademia/OIDC-implementation/wiki#transaction-fail. It is expected the client has sufficient support to display the error and inform the enduser in a usefull way. |
| Validation Time Out |
| If user returns to it after a period of time the session drops due to the 5-min TTL on the servers (which is necessary to avoid overload our infrastructure). |
| User is presented with page not found, domain not found, certificate expired | InAcademia does not present functionality to allow a user to go back to a previous page. | It would be helpful for the merchant to provide FAQs and/or support to students that are using a worflow that contains InAcademia. |