The InAcademia service allows you to easily and securely validate a user’s affiliation in real time with academic institutions in many countries. This guide describes functional and high-level technical considerations and recommendations for implementing InAcademia into your website.
1. About academic affiliation
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 not a factor in the definition of an academic institution.
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.
2. Supported affiliations
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.
As InAcademia builds upon eduGAIN, it draws on the authoritative system of records as 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.
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 requested affiliation.
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. Please note that it is your responsibility to configure any necessary fall back process.
3. Implementing your validation flow
3.1 Common flows
First you must choose which validation flow to implement, as InAcademia can operate in various flows. Common flows used by our customers include:
- Real-Time Validation This is the validation flow which proves the best real-time results, where a user needs to validate when completing a purchase, 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. This scenario always requires users to validate. In this context you will have to design your implementation so that it’s clear to the users that validating as an academic affiliate (for example, a student) gives them some advantage (for example, benefiting from a discount or access to a restricted service). It is also possible to combine this scenario with validation at registration.
- Registration Validation In this case, you ask a user to validate the affiliation as part of the registration at your website. 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. You may decide to validate only at registration time and not later-on at the time of transaction. If you decide to implement this workflow, it’s important that you realise 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 if the user then carries out a transaction in the future, it does not guarantee the user is still a student at this later point in time. For this flow it is recommended to configure your systems to request a new validation periodically, e.g. at least once per college year (typically September to July) 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 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).
- Cash-back after validation In this scenario you provide for example a cash-back option where the user purchases a product and is afterwards able to prove a required affiliation. The benefit to you in this case is that the sale was already committed, but it may require more work to implement than the options above.
3.2 IdP hinting
IdP hinting is an extension to the InAcademia service that intends to assist merchants who are keen to reduce the number of clicks a student needs to make in validating a sale or registration process, and can also be used in offering services to use cases in specified countries. By making a list of uniquely referenced institutions available on a country-by-country basis, it is possible for the merchant to target specific countries, institutions or subsets of institutions with specific campaigns.
3.3 User Experience
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 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.
4. Register your client
To make use of InAcademia, you need to implement 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 of you being in control of these endpoints, as described on the registration page.
It is also strongly encouraged to register separate clients for various stages of your development, like e.g. “dev”, “test”, “production” and reflect this 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 against using test clients.
5. Implementation considerations
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 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.
6. Validation Request
To construct a validation request you need to consider a few aspects of the request:
- Identifier usage When implementing a flow, you need to choose between requesting a transient identifier and a persistent identifier. Using a transient identifier (default) may suffice in cases where you only need to establish the affiliation. A persistent identifier, or the Reuse Detection feature, allows you to identify a returning user subsequent to the first validation, provided that the required attributes are supported and released by the institution, and where the validity of the identifier depends on the institution maintaining its persistence, and as such may be appropriate in case you want to hand out a specific discount only once. Note that the InAcademia Service is unable to guarantee any period of persistence as changes regarding the release of persistent identifier made at the IdP level after the user has first logged on will invalidate the identifier. 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 with GDPR requirements and considerations. Refer to https://inacademia.org/inacademia-and-privacy/ for further information. A more privacy preserving alternative is the transient identifier, however, this will not allow the merchant to identify returning users validating with the same academic account.
- Requested validation In order to minimise the amount of personal data exchanged for the validation, you may only ask the InAcademia service to validate a specific affiliation from the supported set, either ‘student’, ‘staff+faculty’, ‘employee’ or ‘member’. This gives you certainty that you’re validating the specific affiliation of your target market. It is possible to validate a more broad affiliation with the institution by requesting the validation of ‘member’. Any user that is either ‘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 rejected validation, but it does mean you cannot target specific affiliations (see also the section below on ‘Validation Response’).
- Facilitate institution selection For end users to be able to validate their affiliation, it is required that they use their home institution to log in. InAcademia is intentionally unaware who the user is at all stages of the process. It is necessary for the merchant to decide whether it intends to present a list of supported/eligible institutions to the user from its own database and to map those towards the in-scope institutions for InAcademia (using IdP Hinting) or whether it would prefer that InAcademia presents a list of institutions from which the user can select its own. In the first scenario, a user selecting an institution from your database will be automatically directed to the login page at that institution. For the second scenario, InAcademia will present the user with a screen that invites them to select their home institution. It will be necessary to decide between the two options and, if IdP Hinting is selected, use of this feature must be included specifically in your implementation design. Your implementation and testing must consider the scenario where the academic 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 idp_hint or aarc_idp_hint parameter.
- 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. 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 ID will be provided where persistent ID 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.
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 firstname.lastname@example.org 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. 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.
7. Managing Validation Responses
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 that matches, the InAcademia service will positively respond to your client. Depending on the request, this response will include a confirmation of the requested validation, the user identifier of the requested type, and may also assert the institution 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, 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 should 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
In rare cases a user may not be able to complete a validation transaction at all. This could occur if:
- the user terminates or simply stops completing the process, 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 mitigate against this, it is recommended you periodically check your internal system for such stale transactions.
8. Implementation testing
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 Q2-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:
As indicated by the Success and Fail matrix, these credentials will allow you to test for various ‘happy paths’ and error flows.
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/
9. Go-live testing
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.
Production platform error testing
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.
10. Client migration
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 the 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.
11. Further information
Mitigation for a user forgetting 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. There are, however, scenarios where login and hence validation could fail: these include login failure (incorrect or mis-spelled credentials), 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. 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 receive 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 programatically.
Mitigation against multiple attempts to enter (incorrect) credentials
InAcademia is designed to return access_denied to the return_url of the merchant, but it should be noted that some identity providers will terminate the transaction, 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 in Q3 2022)
Demonstrator that implements InAcademia: https://demoshop.inacademia.org/shop/