InAcademia Implementation Guidelines

Contents

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 Open ID Connect (OIDC) and a REST API. This guide describes functional and high-level technical considerations and recommendations for implementing InAcademia into your website.

It is recommended you read through the OIDC technical implementa tion notes as well.

1. About academic affiliation

InAcademia allows easy validation of a user’s academic affiliation. The validation is based on the authoritative records as managed by the user’s academic institution. Typical academic roles, called affiliations, include “student”, “faculty” or “member”.

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, although this can differ from country to country, as does the mix of public and private academic institutions available via the InAcademia service.

As well as traditional academic institutions, other institution types may also support InAcademia:

A teaching hospital granting internationally recognized academic degree levels.
A research hospital, library or archive.
An institution primarily dedicated to conducting research.

2. Supported affiliations

InAcademia supports four affiliation values:

“student” This user is a student at the institution
“faculty+staff” This user is an academic or professional member of the institution
“employee” This user is an employee at the institution
“member” This person holds any of the above roles 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).

InAcademia relies on the information provided by the user’s institution. 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.

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, employees and students.

Therefore, it’s important that you think carefully about the nature of the validation you’re requesting, and ensure that your implementation, UX design and testing takes into account appropriate error handling and fall back mechanisms. 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.

3. Implementing real-time validation

3.1 Common validation scenarios

Your use case will influence how you design your workflow, but as InAcademia has been implemented in support of at least two high-level use cases:

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 an account registration process. 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 appropriate pricing or discounts to the user. When utilised in this manner, it is recommended that users are prompted 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 eligible at that time, but it does not guarantee the user is still a student at the point of any future transactions. 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 initiate 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 embedding a redirect in an ‘I’m a Student’ button (or similar call to action) 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, for example:

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, skipping the InAcademia Discovery Service. This approach results in fewer steps, helping to create a smoother flow for the user, and can also be used to limit offers to users in specified countries. By hosting a list of uniquely referenced institutions available on a country-by-country basis, and by updating it hourly, we make it possible for the merchant to consume the data to present its own ‘discovery’ 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.

4. Register your client

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.

5. OIDC implementation considerations

The InAcademia service provides an Open ID Connect (OIDC) based API, as described in the OIDC implementation notes. You are free to choose the RP software you would 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.

6. Validation Request

To construct a validation request you need to consider a few aspects of the request:

Transient or Persistent Identifier? During design and implementation, 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. 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). Each merchant receives differing pseudonymous identifiers for the same user – so this prevents building of profiles of a user. 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 is stateless and 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://stage.docs.inacademia.org/knowledge-base/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. Please note that Authorization Code Flow (response_type=code) is recommended, the Implicit Flow (response_type=id_token) is now 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 one specified 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 returned in the OIDC response to the requesting merchant. If the user has multiple affiliations, only the scope relating to the pre-specified affiliation 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 utilise 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 the aarc_idp_hint parameter. This provides additional reassurance that the user has authenticated successfully at the institution that it specified at the discovery step.
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:
- eduPersonTargetedID
- eduPersonPrincipalName
- pairwise_id
- subject_id
- eduPersonUniqueID
- 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, contact us 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, merchants should factor the following into their design:
- Because the identifier returned is pseudonymised, not anonymised, it’s considered personally identifiable information.
- Because InAcademia is stateless, the persistence is maintained by the Institution and so 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.
  Examples:

Returned Scope ‘openid+persistent+member’

{"iss":"https:\/\/op.srv.inacademia.org",
"sub":"3cfa6be478250f039a2181b90bb615d0a6efd8896be179dcc7ead19e2e51a661",
"aud":["InAcademia_Test_Your_Affiliation"],"iat":1665422278,"exp":1665425878,"auth_time":1665422275,
"requested_scopes":{"values":["persistent","member","openid"]},
"returned_scopes":{"values":["openid","persistent","member"]},
"transaction_id":"870dc703-2312-4e89-867c-e2407e2d3a95","nonce":"70d525857195b463be6e55399ad40d38"}

Returned Scope ‘openid+transient+member’, when persistent was requested

{"iss":"https:\/\/op.srv.inacademia.org",
"sub":"e465c1c4b5fdda70d7617f04f11b62cbeff1bf74818c359c4e861ee35a176a51",
"aud":["InAcademia_Test_Your_Affiliation"],"iat":1665422427,"exp":1665426027,"auth_time":1665422406,
"requested_scopes":{"values":["persistent","member","openid"]},
"returned_scopes":{"values":["openid","transient","member"]},
"transaction_id":"e490158d-ac59-4916-9e18-042bbfe027bd","nonce":"1a38d0e7e2c7f5855c43f59e91b0f450"}

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 value provided by the institution to the affiliation value specified 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 user-facing software, 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, or
you requested an affiliation that is not assigned to the user (for example an employee cannot be validated as a student)

The InAcademia service will handle the various happy and unhappy flow responses typically using “Access Denied” messages. For unhappy path responses 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 UX presentation.

It is important that the unhappy flow responses are not served to end users directly. Your design must 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 users, 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 academic affiliation.

Depending on your use case, in order to mitigate issues caused when affiliation cannot be validated, it may be appropriate to first initiate a request for a specific affiliation, for example e.g. ‘Student’, then to configure your implementation to continue to request the validation of a broader affiliation, such as ‘member’ if the ‘Student’ validation request fails.

7.3 Transaction failure

Please note that there are circumstances in which we are unable to serve a response to your client for legitimate technical 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. It is advised to set an appropriate timeout to ensure that the user can try again.

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 a test client_id and client_secret for testing, and we will initiate a Proof of Domain Ownership procedure.

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. Although the integration test platform does 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 test 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 IdPs are as follows:

https://idp.test.inacademia.org/saml2/idp/metadata.php – IDP1 – SimpleSAMLphp
https://idp2.test.inacademia.org/idp/shibboleth – IDP2 – Shibboleth

Both IdPs are intended to mimic the behaviour of a live academic identity provider. It is possible to test both the IdP hinting feature and IdP Hint Assertion claim using these IdPs.

Where an invalid 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 https://idp.nonsense.org/saml2/idp/metadata.php, or any other 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 alongside the result to be expected:

Test Credentials

Credentials		Validation requested
Username	Password	‘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/unhappy paths and error flows.

It is critical that you test your application thoroughly 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 used with the above credentials to give you an idea of how the process works from a user’s perspective. The demoshop resides at https://demoshop.stage.inacademia.org/shop/.

9. Launch

We do not allow clients to connect to the production platform without first having successfully tested within the Integration Test platform. When your testing has completed, please register your production client at “Register your service”. Upon registration you will be provided with a production client_id and client_secret and you will be free to proceed to launch.

Production platform endpoints

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 you to test in production against a live IdP.

10. Client migration

If you plan to update your client software, don’t forget to check whether the redirect_uri will change. If the redirect_uri is likely to change as a result of the update, you will need to adopt one of the following strategies in order 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.

11. Further information

What if a user forgets their credentials?

InAcademia leverages the same identity and access management solutions that users encounter on a daily basis to access academic resources, learning platforms, etc. It is unlikely that a user will forget their login credentials, but if they do it’s important to 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. 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, as described in section 7.

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.