The InAcademia service allows you to easily and securely validate a user’s affiliation in real time with academic institutions in many countries by way of an Open ID Connect (OIDC) based API. This guide describes functional and high-level technical considerations and recommendations for implementing InAcademia into your website.
InAcademia allows for easy validation of a user’s academic affiliation. The validation is based on the authoritative records as managed by the academic institution of the user. Typical academic affiliations include “student”, “faculty” or “member”.
What constitutes an academic institution differs on a per country basis. Generally speaking, an academic institution is a legal entity that is an accepted member of a community that grants academic qualifications, such as degrees, and participates in research activities. Note that the funding mechanism (private, public or mixed) is generally not a factor in the definition of an academic institution, although the mix of public and private academic institutions available via the InAcademia service may differ from country to country.
As well as traditional academic institutions, the following additional institution types may also be using InAcademia to prove academic affiliation:
- A teaching hospital granting internationally recognized academic degree levels.
- A research hospital, library or archive.
- An institution primarily dedicated to conducting research.
- An institution which is explicitly denoted as an academic institution by a government entity or recognized accrediting body in the jurisdiction where the claim of being an academic institution is made.
InAcademia supports 4 possible values for affiliation validations to be requested:
- “student” This user is a student at the institution
- “faculty+staff” This user is a teacher/researcher (faculty) or a worker (other than teacher/researcher, staff) at the institution
- “employee” This user is an employee at the institution
- “member” This person is either a member, student, faculty, staff or employee at the institution (please note that in this case, when a merchant requests the ‘member’ scope/affiliation in its OIDC request, InAcademia will not distinguish whether the user is a student, staff, faculty or employee in its response, but will assess whether any of the affiliation values received are either member, student, staff, faculty or employee before returning the validation result).
With regards to the affiliations supported by InAcademia, it should be noted that InAcademia relies on the information provided by the institution of the user. What constitutes a student, staff or faculty, employee or member is defined by the institution in the local or national context of the institution. ‘Student’ may for example include both full-time and part-time students, and InAcademia will not distinguish between the various types.
InAcademia builds upon eduGAIN, and so it draws on the authoritative system of record that are used by the institution itself for managing access to its internal services like the user’s email, learning and exam platform(s) or e.g. a HR application or an active directory system.
Some users may hold multiple affiliations at the same time (e.g. a ‘student’ may also be ‘staff’ and/or ‘member’). InAcademia will in that case only confirm the affiliation that is included in the Authentication Request from the merchant, and InAcademia will only validate one affiliation per request.
It is also possible to request validation of a more generic affiliation with an academic institution by requesting ‘member’. This affiliation may include faculty, staff, students, and other persons with a full set of basic privileges that go with membership in the university community. The validation of ‘member’ status is roughly equivalent (but more accurate) to the commonly used method of checking if a user has access to an institutional email address.
Therefore, it’s important that you think carefully about the nature of the validation you’re requesting, and ensure that your implementation design and testing takes into account appropriate error handling and fall back mechanisms. You must also decide how your user’s journey should be designed. It is strongly recommended that you also offer a fallback mechanism outside of InAcademia to validate the user’s affiliation as, there are some institutions within each country that are not available via InAcademia, and because some users will attempt to validate as a student, even though they’re not affiliated with any institution and are not students. Please note that it is your responsibility to configure any necessary fall back process.
3.1 Common validation scenarios
Your use case will influence how you design your workflow, as InAcademia facilitates at least two high-level use cases, such as:
- Discount Validation where a user needs to validate its academic affiliation when completing a purchase in order to qualify for a special offer, typically as part of a checkout process. As this provides real-time confirmation of a user’s affiliation it is trustworthy and up-to-date validation confirmation. The validation process will need to be designed into the checkout process, in such a way that it does not interrupt the user journey, and that it’s clear to the users that to validate as an academic affiliate such as a student gives them some advantage (for example, benefiting from a discount or access to a restricted service).
- Registration Validation In this case, you ask a user to validate their academic affiliation as part of the registration process for access to a service. Whilst the registration process might be online this scenario can also apply to offline contexts, such as access-controlled services such as gyms, where the service is offline, but the subscription is managed online. Knowing your user has a specific affiliation may help you provide access to specific services or to present certain discounts available to the user before a choice is made. It is recommended that users are asked to validate their academic affiliation both at the initial registration, and again at regular periods, to avoid continued use of the service when the user ceases to be a student or academic user. A successful validation at the point of registration assures the user is, for example, a student at that time (as the validation is in real time), but it does not guarantee the user is still a student at the point of any future transactions. Therefore, to ensure users continue to be eligible to use the service, additional requests should be made at least once per college year to make sure a user is still holding the appropriate affiliation. It is up to you to decide if periodic re-validation is appropriate. There are various ways you might choose to implement this, including embedding the request process according to business rules you define, or using your internal customer contact systems to send out a request via email inviting the user to re-validate (potentially with the option to suspend the discount if there is no response).
In all scenarios, it is recommended that merchants avoid use of pop-up windows, but it might be appropriate to consider opening a new tab for the user at the point of validation in order to help mitigate the risk of a user that abandons the validation process for legitimate reasons becoming ‘lost’.
3.2 Helping the user find its institution: whether to redirect automatically or allow a user to search?
There are two methods for directing a user to the correct institution for authentication and validation of their academic affiliation, and it will be necessary for merchants to decide which is the most appropriate method to use in its flow. The two methods are compared in our blog about IdP hinting.
3.2.1 Allow the user to search for the institution using a Discovery Service
This is the default method, where the user validation is initiated by embedded a redirect in an ‘I’m a Student’ button on your website, that is designed to direct the user to its institution for authentication, before being returned to complete the registration/purchasing process, using any one of our branded buttons:
3.2.2 Automatically redirecting the user via the IdP Hinting Feature
Our IdP Hinting feature is an extension to the InAcademia service that helps merchants to automatically redirect a user from its registration/sales process straight to the user’s preferred institution, where the user is asked to authenticate. This approach results in fewer steps, helping to create a smoother flow for the user, and can also be used in offering services to use cases in specified countries. By hosting a list of uniquely referenced institutions available on a country-by-country basis, we make it possible for the merchant to target specific countries, institutions or subsets of institutions with specific campaigns. Please note that IdP hinting is available only to customers of the premium version of InAcademia.
3.3 User Experience during Institution Discovery
Please bear in mind that anything that interrupts the flow of your user’s journey will potentially impact whether a user is able to carry out an end-to-end validation. Therefore, it’s important that you consider how the full flow will work in practice across platforms, operating systems and browsers. When you redirect a user to the InAcademia Service, InAcademia will create a SAML request directed to the user’s home institution (IdP). IdPs are based on various technologies, not all of which would be designed to be mobile responsive. Also, users might employ third-party browser plugins to block pop up windows, therefore it’s important that the design takes factors such as these into account. After the user has authenticated at its home institution, the user will be asked to consent to sharing the result with your service. It will be necessary to gracefully handle both the ‘accept consent’ and ‘decline consent’ scenarios within your workflow.
To make use of InAcademia, you need to implement OIDC client software on your site to communicate with the InAcademia service. Furthermore, your client(s) needs to be registered by InAcademia, to create a trusted connection between your site and the InAcademia service. To complete the registration process, please follow the instructions as described on the InAcademia registration page.
Please note we only accept endpoints which make use of https. As part of registering your client endpoints we ask for proof that your organisation is in control of these endpoints, as described on the registration page.
It is also strongly advised that merchants register separate clients for various stages of development, like e.g. “dev”, “test”, “production” and that the scope of use is reflected in the name of your client. This is particularly useful for your and our understanding in interpreting the usage of the service by your client(s) as well as for issue resolution, should they occur, and you will be able to utilise InAcademia’s pre-production platform to test your implementation using test OP and IdP clients.
The InAcademia service provides an Open ID Connect (OIDC) based API, as described in the technical implementation. You are free to choose the client software you like to connect with the InAcademia service. We strongly recommend, however, making use of an existing product or library which has been certified by the OIDC Foundation. A list of these can be found on the certification website of the OIDC foundation, under “Certified Relying Parties”.
However you choose to proceed, you must refer to the best practices defined here https://openid.net/specs/openid-connect-core-1_0.html when building an implementation and ensure that your software is configured to decode, verify the signature and inspect the id_token that is returned by InAcademia.
As part of the InAcademia documentation, a few example client implementations are provided. Please note that provision of these examples does not in any way signify an endorsement to use these specific clients, nor do we provide support on any client installation you may choose to implement.
When implementing the client, you will need to consider the following additional elements.
To construct a validation request you need to consider a few aspects of the request:
- Transient or Persitent Identifier? During design and implemention, you need to choose between requesting a transient identifier and a persistent identifier.
- ‘Transient´ identifier: When using this profile, the service will construct a pseudonymised transient identifier along with a simple confirmation of the user’s affiliation (using either the ePSA or ePA attributes); the identifier cannot be used to identify the user. Using a transient identifier (default) may suffice in cases where you only need to establish the affiliation.
- ‘Persistent’ identifier. When using this profile, InAcademia will return a pseudonymous persistent identifier. Different merchants will receive different pseudonymous identifiers. The identifier is constructed in such a way that it cannot be traced back by the merchant to identifier(s) provided by the home institution. The pseudonymous identifier will however remain the same in subsequent calls (by the same merchant) to InAcademia for the same user subsequent to the first validation, provided that the relevant attributes are supported and released by the institution. This is useful for ‘one per person’ style offers, where merchants need to be able to check whether a user already benefited from this offer before (thus InAcademia can assist here without divulging any personal information to the merchant). Different merchants receive different pseudonymous identifiers for the same user – so this prevents building of profiles of a user by colluding services. Note that the validity of the identifier depends on the institution maintaining the identifier’s persistence, and therefore the InAcademia Service is unable to guarantee any period of persistence as changes regarding the release of persistent identifiers made at the IdP level after the user has first logged on will invalidate the initial identifier.
- In either case, InAcademia will only store the identifier for logging and de-bugging purposes and storage is limited to 28 days, therefore, it is the responsibility of the merchant to store the identifier in line with GDPR requirements and considerations. Refer to https://inacademia.org/inacademia-and-privacy/ for further information.
- Response Type (e.g., Authorisation Code Grant or Implicit Flow)? Please refer to https://openid.net/specs/openid-connect-core-1_0.html for detailed information when deciding upon the most appropriate response type for your situation. Please note that Authorization Code Flow (response_type=code) is recommended, the Implicit Flow (response_type=id_token) is supported but no longer recommended (deprecated) and the Hybrid Flow (using other Response Type values defined in OAuth 2.0 Multiple Response Type Encoding Practices [OAuth.Responses]) is not supported.
- Requested affiliation to be validated You may only ask the InAcademia service to validate a specific affiliation from the supported set, either ‘student’, ‘staff+faculty’, ‘employee’ or ‘member’. The ‘member’ affiliation makes it possible to validate a more broad affiliation with the institution. Any user that is either ‘member’ (without more specific affiliation), ‘student’ or ‘staff + faculty’ or ‘employee’ will fit into that affiliation, therefore, this option widens the validation to include a larger subset of the academic community and may reduce the chances of a denied validation. The affiliation is also known as the ‘scope’; the scope relating to the user’s affiliation is included in the OIDC response sent to the requesting merchant. If the user has multiple affiliations, only the scope relating to the specified affiliation to be validated is returned, and merchants may only request validation of one affiliation per OIDC request.
- Facilitate institution selection Please refer to section 3.2 above on Institution Selection. When configuring an OIDC authentication request towards InAcademia you must decide whether to direct the request towards the Discovery Service (using the Discovery Endpoint) or whether to use the IdP Hinting feature. In order to utilise the IdP Hinting Feature it is necessary to include a supported and correctly encoded IdP Hint as provided here https://github.com/InAcademia/aarc_idp_hint. Note that you must only utliise IdP Hints for the countries in which you are licensed to use InAcademia. This will be referenced in the agreement between your organisation and the InAcademia service. Your implementation and testing must consider the scenario where an institution is not supported and hence InAcademia cannot be used for validation of the users affiliation. In this case you should present an alternative route of your own design for proving their affiliation. See below for further information.
- IdP Hint Assertion feature The InAcademia service will return the hint of the requested IdP in the id_token by default when expressed using either the aarc_idp_hint parameter or idp_hint (deprecated at 31st August 2022) parameter.
- Returning users The Re-use Detection feature is capable of retrieving information from the institution that allows merchants to identify whether a user has already consumed a one-per-user offer. This feature will request any one of five possible persistent attributes to be returned in the response by the institution’s IdP. A merchant that includes the ‘reuse_detection’ claim in its OIDC request, will elicit a response from the InAcademia service containing a pseudonymised hash of any of the following supported persistent identifiers (provided they are received from the IdP) as a series of values that merchants permitted to use the persistent flow can utilise in order to recognise a returning user:
- Persistent NameID
- This feature is available provided that the client_ID is configured for the ‘reuse_detection’ claim in the InAcademia backend. If you wish to utilise the reuse-detection feature, please specify as such during registration or, if you choose to use this feature later on, send an email to email@example.com to request the addition of the reuse_detection claim as an allowed claim for your client. Upon confirmation that this addition has been completed, you can include the reuse_detection claim when initiating a validation request. Please note that it is only available to users of the premium InAcademia service.
Further information on the Re-Use Detection Feature:
- InAcademia will also return the identifier as a sub, which is also subject to backend configuration prior to use. Note that when Persistent NameID and eduPersonTargetedID are returned via the IdP containing the same values, the hash values will also be the same in the reuse_detection claim. Whilst it can be useful in preventing abuse of application for one-time student offers, the downside of this feature is that:
- Because the identifier returned is pseudonymised, not anonymised, it’s considered personally identifiable information.
- Because InAcademia does not store data for more than 28 days, the persistence is maintained by the Institution and not by the InAcademia service. That is, if the Institution changes the source value, the hashed value returned in future sessions will differ to that originally created.
- Not all IdPs release persistent attributes, and so it might not be possible for InAcademia to construct a persistent identifier.
In the event that the merchant requests a persistent identifier to be included in the response directed towards an institution that does not release persistent attributes, InAcademia offers a feature that will return a transient identifier in the ID token, flagging it as such, instead of terminating the session without validation. This means that merchants using this feature will still be able to determine the level of discount to offer to the user, based on their affiliation being validated, but without the ability to identify if they return to request the same offer in future.
In this case, a transient, pseudonymised identifier will be provided where persistent identifier has been requested but cannot be constructed. The response will include the relevant ‘scope’ parameter in the OIDC authorization response indicating the processed scopes, in accordance with OIDC specifications, confirming whether the identifier is transient or persistent. Examples follow below. Therefore, in the case when transient ID is provided to the RP instead of the requested persistent ID, ‘transient’ is part of the scope parameter instead of ‘persistent’. This will allow merchants to detect this scope and configure its workflow to decide to proceed using the transient identifier or to request alternative validation.
The request will elicit a list of multiple possible identifiers and it will be necessary for your systems to store those identifiers independently and in such a way that it is meaningful for the client to use. Please note that OIDC clients configured with this claim will only be permitted to use the persistent flow, and the InAcademia team will require additional assurance from the merchant that the request to use this feature is warranted, relevant and not excessive for the specified use case. In the event that the request to use this feature is perceived to be not relevant or excessive for the specified use case, InAcademia reserves the right to reject the request, in order to maintain compliance with the GEANT Code of Conduct.
After InAcademia receives your client’s validation request it will ask the user involved to prove the affiliation to InAcademia by authenticating against the user’s home institution.
7.1 Validation success
Upon receiving the response from the user’s institution, the InAcademia service compares the affiliation provided by the institution to the affiliation requested by your client. If they match, the InAcademia service will positively respond to your client. Depending on the request, this response will include all scopes and clwithin the ID Token, including a confirmation of the requested validation, the pseudonymised user identifier of the requested type, and may also assert the IdP Hint that was the subject of the request.
7.2 Validation failure
As with any system, you must always take into account the scenario in which the affiliation you are requesting cannot be validated. This could occur when:
- the request was not constructed correctly (refer to the scenarios here)
- the user was not able to authenticate because of an error at the IdP, or
- the user is not affiliated with the institution because the user’s affiliation expired or the user wasn’t ever affiliated to the institution in question, or
- the user does have a relationship with an institution, but the institution has not released the affiliation value to InAcademia
- you requested an affiliation that is not relevant to the user (for example an employee cannot be validated as a student)
The InAcademia service will handle errors typically using “Access Denied” messages. In such a case you must always present a user with a proper error message when needed and it is your responsibility to configure your website’s error handling workflow and to decide how to present the error in your customer-facing and internal systems.
It is important that you note the error messages presented to your client by the InAcademia Service are not intended to be served to end users directly. You must therefore interpret the errors and present the user with a message in the context and/or language of your service. Please also note that the InAcademia Service does not support end users directly, therefore, it is not allowed to direct your customers or end users to seek support from the InAcademia Service. Doing so would result in suspension of your service. Instead, it is advised that you consider presenting a message to your end user using your customer-facing systems, such as ‘Are you sure that you’re affiliated with the Institution you’ve selected? If so, please contact your Institution’s IT Administration team. For all other queries, please contact…’ and to present them with an alternative route to proving their affiliation with that institution.
Depending on your use case, in order to mitigate against issues caused when affiliation cannot be validated, it may be appropriate to first ask for a specific affiliation, for example e.g. ‘Student’, then if the ‘Student’ validation request fails to configure your implementation to continue to request the validation of a broader affiliation, such as ‘member’.
7.3 Transaction failure
Please note that there are circumstances in which we are unable to serve a response to your client for legitimate reasons. These scenarios are:
- the user abandons the process for a period of time, and either the InAcademia session or the merchant session timesout,
- the session is interrupted in such a way that is was not possible to recover the state,
- your OIDC authentication request did not contain a client ID or redirect uri.
In such scenarios, InAcademia will provide an error to the user advising them to return to the service they were using at the point that the error occurred.
Note that sometimes it may not be possible for InAcademia to return a response to the user:
- the user terminates or simply stops completing the process, or
- the user was not able to authenticate because the do not have an account at the chosen institution, or
- a technical issue prevents the validation transaction to complete, like e.g. networking issues, or institutional login service is not available.
In such cases the transaction flow stops and InAcademia is not able to inform you of any status with regards to this transaction.
To properly test the implementation of your client, you need to first test against the InAcademia integration testing platform. To connect to the test platform you must have completed client registration as described in the “Register your client” section. Upon registration you will be provided with credentials for testing.
To use the integration testing platform, you need to use the following endpoints:
Discovery endpoint: https://op.srv-test.inacademia.org/.well-known/openid-configuration
Authorization Endpoint: https://op.srv-test.inacademia.org/InAcademia/authorization
OIDCProvider Issuer (optional): https://op.srv-test.inacademia.org
Once connected you can use your client to trigger validation requests towards the integration platform. The platform is a production-like version of the InAcademia service and allows you to test your integration including various claims and flows. The integration test platform does however not provide capability to use a real institutional identity provider to test against. It is possible to initiate requests to either a Shibboleth or SimpleSAMLphp identity provider. This can be achieved either by selecting the required IdP from the test discovery service, or by utilising the IdP hinting technique.
The hashes for the IdPs are as follows:
- https://idp.test.inacademia.org/saml2/idp/metadata.php – IDP1 – SimpleSAMLphp
- https://idp2.test.inacademia.org/idp/shibboleth – IDP2 – Shibboleth
idp_hint/sha-1 (deprecated from 31st August 2022)
- b8b8bcb6902ad3c4b73be3debf6edae469bccec2 – IDP1 – SimpleSAMLphp
- 7223b4b25d467f44502ebe382547c60d17e4f193 – IDP2 – Shibboleth
Both IdPs are intended to mimic the behaviour of an Academic identity provider. It is possible to test both the IdP hinting feature and IdP Hint Assertion claim using these IdPs.
Where an un-readable IdP hint hash InAcademia is designed to return the user to the merchant redirect_uri in this scenario. Merchants are able to test this behaviour by using a simple hash, such as 1234567890123456789012345678901234567890, or an invalid entityID.
Test credentials A set of test user credentials is available to mimic the kinds of profiles typical users have. The table below shows which credentials may be used:
Table: Test Credentials
As indicated by the Success and Fail matrix, these credentials will allow you to test for various ‘happy paths’ and error flows.
It is critical that you test your application thoroughly again with these credentials to make sure you support all possible flows, including potential error situations that may occur.
Demo shop The InAcademia demo shop is a simplified test webshop that showcases how InAcademia might be used to provide a discount after successful validation of a student. The demoshop makes use of the Integration testing platform and can be tested with the above credentials to give you an idea of how to implement happy flow and potential error handling. The demoshop resides at https://demoshop.inacademia.org/shop/ (please note that the demoshop has been designed with only functionality in mind).
We do not allow your client to be connected to the production platform until you have successfully tested within the Integration Test platform.
Production platform endpoints
To connect to the production platform you will have to configure your client to make use of the production platform, as described in the technical implementation guide.
Discovery endpoint: https://op.srv.inacademia.org/.well-known/openid-configuration
Authorization Endpoint: https://op.srv.inacademia.org/InAcademia/authorization
OIDCProvider Issuer (optional): https://op.srv.inacademia.org
Production platform testing
It is important to note that very few academic institutions support test accounts, and therefore it is not possible for specific IdPs to be reached during testing.
If you need to move your client software to a new platform two strategies may be adopted to mitigate loss of the InAcademia service:
10.1 Register multiple client endpoints
You may register multiple client endpoints per client_id. It is your client that initiates a transaction, and as part of that informs InAcademia of the preferred redirect_uri. In this way you may steer your user to your new client at your convenience. To register a new client for an existing client_id, you must contact InAcademia support prior to making any change.
10.2 Change DNS
InAcademia only registers client endpoints based on FQDN names. As the DNS for these names is under your control, you can run both the old and the new client at the same time and update DNS to point to the new client at your convenience.
What if a user forgets their credentials?
InAcademia makes use of university sign-in systems to validate if somebody is a student or faculty. Note that there is no ‘back’ button available to the user at the point that they are invited to sign into their home institution. This is standard practice in federated identity scenarios. This login is used by the users on a daily basis if they are active users in their institutions as the very same login is needed for access to e.g. their email, learning platform or HR systems, etc, and it is therefore fairly unlikely a user cannot remember the correct credentials. If the user cannot authenticate they cannot proceed until they have resolved the issue by using ‘forgotten password’ routines at their home institution. There are, however, scenarios where login and hence validation could fail: these include login failure (authentication error at the IdP), a user no longer being part of an institution or the user not being of the requested affiliation. In all such scenarios InAcademia will return an “access denied” error indicating validation has failed and the flow is then handed back to your application.
Mitigation for users with multiple affiliations
Sometimes it is necessary for a user to validate for Offer A with one type of affiliation, but another type of affiliation for Offer B. If a user has multiple affiliations, and has already validated for Offer A that requested validation of the ‘student’ affiliation (for example) and ended their session, and then if that user initiates a new session at your endpoint, where the request includes a different scope, they will be asked to authenticate again, and InAcademia will compare the affiliation returned by their home institution’s IdP to the scope requested.
If a user has more than one account, each with a different affiliation type, and accidentally chooses an account that does not return the requested scopes, the user’s validation may be declined despite the user having successfully entered the correct credentials for that account. In this scenario, as the IdP SSO session is typically set at the user’s browser, the user would need to log out at the institution before trying again with the correct account. There is a small percentage of users that may have a student affiliation at institution A and a staff affiliation at institution B. The only way to switch between these identities is for a user to logout at the institution and to select an alternative institution during the discovery process.
Mitigation for users logging in at public workstations
In settings where the users are regularly invited to register in person using a public terminal, there is a risk that if the previous user does not close the browser and clear the session after their login, the next user might automatically inherit the session of the original user. In this context it is strongly recommended that the login process is designed so as to forcibly terminate the browser and clear the session as a whole programmatically at the point where a user completes its registration.
What if a user makes multiple attempts to enter (incorrect) credentials?
Some identity providers will terminate the transaction after a specified number of failed login attempts (without giving the opportunity for InAcademia to complete the session with an access_denied response), others will process the transaction and return authentication failure allowing InAcademia to return access_denied.
The technical client implementation documentation: https://inacademia.org/oidc-implementation-for-inacademia/
Example client configuration for exiting client software: https://inacademia.org/client-rp-examples/
Endpoint for AARC IdP hint data: https://github.com/InAcademia/aarc_idp_hint
Endpoint for sha1 IdP hint data: https://github.com/InAcademia/idp_hint (scheduled for deprecation 31st August 2022)
Demonstrator that implements InAcademia: https://demoshop.inacademia.org/shop/
OIDC best practice: https://openid.net/specs/openid-connect-core-1_0.html