Deployed to production 9th May 2022.
The address of the repository containing the aarc_idp_format hints to be used is https://github.com/InAcademia/aarc_idp_hint. This repository is structured in the same manner as the repo that you have been using to date.
The sha1 hash-based method of IdP hinting and the ‘idp_hint’ parameter will be removed from support in a future release of InAcademia, currently planned for August 2022, allowing 3 months for merchants to update its workflow to support the aarc_idp_hint parameter in all requests.
If the hint received does not resolve to valid metadata InAcademia will return access_denied+error description=entityID error to the redirect_uri, in which case the user will be returned to the merchant.
-----------------
This update means that there is now a more direct link between the InAcademia IdP Hinting feature and the published eduGAIN entityIDs. Whilst this is not a breaking release today, it will be necessary for merchants to make adjustments in the construction of their OIDC requests to InAcademia prior to the existing method being deprecated in the summer.
The InAcademia service will continue to support the current method of initiating the IdP Hinting feature (using the ‘idp_hint’ parameter or ‘idp_hint’ claim where currently configured), for a period of three months in order to facilitate merchants in migrating to the new OIDC request format during that time.
The timeline is summarised as follows:
Milestone | Timeline | Status |
Deploy to InAcademia pre-production environment for preview | 1st April 2022 | Complete |
Publish planned release date | 20th April 2022 | Complete |
Deploy to InAcademia production environment (enabling aarc_idp_hint parameter and the use of entityID-based hints) | 9th May 2022 | Complete |
Publish deprecation date (for idp_hint parameter and sha1-hash hints) | 31st August 2022 | Complete |
Deprecate idp_hint parameter and support for sha1-hash hints | Q3-2022 |
The release comprises the following enhancements:
Up to and including v3.2.0 | Upgraded feature |
IdP Hinting requires a SHA1 hash-based hint (as supplied by InAcademia in JSON format) to be included in the OIDC request using the ‘idp_hint’ parameter or claim. e.g. idp_hint=c50752ce1d12c2b37da13a1a396b8e3895d35dd9 | The AARC IdP Hinting feature requires a URL-encoded entityID hash (to be supplied by InAcademia in JSON format) to be included in the OIDC request using the new ‘aarc_idp_hint’ parameter. e.g. aarc_idp_hint=https%3A%2F%2Fidp.nordu.net%2Fidp%2Fshibboleth Support for SHA1 hash-based hinting to be deprecated in Q3-2022. |
InAcademia specifies and supplies hashed hint values in the form of per-country JSON files. These JSON files are intended to be utilised by the merchant to consume and create a UI drop-down (using the ‘display name’ of the institution inside the JSON file) from which users* can select their home institution. This design supports merchant workflow to initiate a request to InAcademia using the hint associated with that home institution, where the user is directed to the related institutional identity provider using the InAcademia service based on the related sha1 hash. *(where the user is registered at an institution in the country where the merchant is licensed to use InAcademia) | The repository containing the per-country JSON files comprising entityID-format hints is available here: https://github.com/InAcademia/aarc_idp_hint. e.g. “https://idp.nordu.net/idp/shibboleth” “en”: “NORDUnet” “no”: “NORDUnet” Provision of SHA1 hash-based JSON files to be deprecated 31st August 2022. |
InAcademia falls back to a Discovery Service if the hint value cannot be reconciled to an entityID. This allows the user to select the most appropriate IdP from the DS and move on. This has the following downsides: · Observation from live operations demonstrates that users are 30% more likely to abandon their session if they reach discovery unexpectedly. · The Discovery Service currently relates to all global IdPs, and is not restricted to in-scope countries. · If the user hits ‘back’ the experience can be unpredictable. | If the received hint does not resolve to valid metadata InAcademia will return access_denied+error description=entityID error, returning the user to the merchant, thereby allowing the merchant to decide how to proceed in this scenario. Please refer to the link below for the updated flow diagram: https://wiki.geant.org/display/InAcademia/InAcademia+Functional+flow+with+errors |
The currently optional IdP Hint Assertion feature allows merchants to include the ‘idp_hint’ claim that allows merchants to identify users who are directed to an IdP contrary to that selected in the merchant UI. | The IdP Hint Assertion feature is now enabled as default for all merchants, and is initiated by the parameter (rather than requiring an additional claim). |
What does this mean for merchants? Using an entityID-based IdP Hint means that merchants now need to:
- work towards the inclusion of a correctly URL-encoded entityID parameter in the GET request using the ‘aarc_idp_hint’ parameter (instead of the ‘idp_hint’ parameter), and
- remove the IdP hint hash from any claims, and
- handle users returning to the redirect_uri as a result of an invalid/stale hint being used in the request.
This needs to be concluded by August 2022 (exact date will be confirmed soon).
Requests using the sha-1 hash towards InAcademia appear as follows:
&state=17edc5989051dd5ce2858ac09f30b3cd&scope=openid+transient+member&idp_hint=c50752ce1d12c2b37da13a1a396b8e3895d35dd9
They should be constructed to use the aarc_idp_hint parameter in the following format:
&state=5989051dd5ce2858ac09f30b3cd&scope=openid+transient+member&aarc_idp_hint=https%3A%2F%2Fidp.nordu.net%2Fidp%2Fshibboleth
The test IdPs in the aarc_idp_hint format are as follows:
- https://idp.test.inacademia.org/saml2/idp/metadata.php - IDP1 - SimpleSAMLphp
- https://idp2.test.inacademia.org/idp/shibboleth - IDP2 - Shibboleth
The InAcademia product team would be happy to participate in one-to-one meetings to discuss these changes further with your product teams. In order to schedule a discussion, please contact info@inacademia.org.