InAcademia Implementation Guidelines

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.

If you are also making the technical client implementation, it is recommended to to read through the technical implementation as well.

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 student, faculty, staff or employee at the institution

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. A faculty member is probably also an employee. A ‘student’ may also be ‘staff’ if this student has a teaching or research role at its university. 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.

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.

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:

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. Because of the transitive nature of this validation, the transaction is typically equivalent to ‘anonymous’ and as such comes with significantly less GDPR requirements. A persistent identifier 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. On the other hand, 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. Also this request requires you to store the identifier as part of a user profile and storing such data comes with GDPR requirements and considerations. Refer to https://inacademia.org/inacademia-and-privacy/ for further information.
  • Requested validation To reduce the amount of personal data exchanged to the minimal level, you may only ask the InAcademia service to validate a specific affiliation from the supported set, either ‘student’, ‘staff+faculty’, ‘employee’ or ‘member’. This also 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’).
  • Requesting additional information If needed, you may also request that the service asserts that the user is affiliated with the institution that was subject of the request.
  • 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. The user will be presented with a screen that invites them to select their home institution. Depending on your use case, the user may have already specified their institution in your workflow. In this case, to improve the user experience, InAcademia provides a feature called Identity Provider Hinting, which helps you to present a list of supported institutions. This list can then be used to inform the InAcademia service of the preferred institution to use for validating the user’s affiliation. Upon receiving such a hint as part of the validation request, InAcademia will forward the user to the selected institution directly, without the need for the user to select his/her institution again. 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.

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 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 just not the affiliation value
  • you requested an affiliation that is irrelevant 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.

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. As part of the validation you will be directed to a test identity provider that mimics one of an Academic institution. As there is only 1 test identity provider connected to the test platform you may request an IdP hint, however, the requested IdP will be ignored and instead the test IdP will be presented always.

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:

Username Password Validation requested      
    ‘student’ ‘staff+faculty’ ‘employee’ ‘member’
student1 student1 Success Success Success Success
student2 student2 Success Success Fail Success
professor1 professor1 Fail Success Success Success
staff1 staff1 Fail Success Success Success
member1 member1 Fail Fail Fail Success

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
When using the production platform, InAcademia will be able to support validations with all configured identity providers. As very few academic institutions support test accounts, you may make use of an identity provider called “eduGAIN Access Check” to test your platform in the production phase.

The InAcademia support team will provide you with test credentials for this identity provider, which will be valid for a period of 3 months upon request. To request a new set, please contact InAcademia support as described in the Service Policy.

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.

IdP Hinting
Once connected to the production platform, you may also test the IdP hinting feature

To invoke the eduGAIN Access check IdP, please use the following identifier in your request: eduGAIN Access check is registered in Renater Federation: "dfa354b9ce577a7f71441d5af473525ea3b12dd8": { "en": "eduGAIN Access Check", "fr": "eduGAIN Access Check" },

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

Typically if a user has multiple affiliations, this does not require a new login at the institution. The institution will provide InAcademia with both affiliations, allowing either to be used for validation. If you need to ask for another affiliation, you clear out your local session, then make sure you make a request with new session, a new nonce and a new state. 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.

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

12. References

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 IdP hinting data: https://github.com/InAcademia/idp_hint

Demonstrator that implements InAcademia: https://demoshop.inacademia.org/shop/