OIDC Implementation for InAcademia

The InAcademia service uses the OpenID Connect standard to provide validation of an end-users affiliation with an academic institution. In this protocol the InAcademia service acts as an OpenID Connect provider (OP), and to validate an affiliation your service acts as a Relying party (RP).

This document is NOT a complete implementation reference for an OIDC RP for InAcademia. To ensure that the full benefits of the OpenID Connect standard and the InAcademia service are realised, it is strongly recommended that merchants use an OIDC client that has passed the OIDC certification (as listed here: https://openid.net/certification/ in the section “Certified Relying Parties”). This document assumes you are using an existing RP or RP library and provides suggestions on how to configure your client in general terms for use with InAcademia.

Examples of configuration for specific clients can be found here: https://inacademia.org/client-rp-examples/

More best practice information can be found here: https://openid.net/specs/openid-connect-core-1_0.html

In ‘Transaction: validate affiliation’ the protocol flow and the messages exchanged in one transaction are described. All supported operations are described more in-depth in Supported operations.

Terminology and legend

In addition to the terminology defined by OpenID Connect standard, here follows some clarifications and additional terms used in this document.

Table: Terminology

Term Clarification
Relying Party (RP) Part of your service acting as a client of the InAcademia service using the OpenID Connect protocol.
OpenID Provider (OP) The InAcademia service.
Institution The academic institution the end-user is affiliated with.
Transaction One validation of affiliation at the InAcademia service. A transaction starts when the InAcademia service receives a valid OpenID Connect authentication request, and ends when the response of the validation is returned via the redirect URI.

Table: Formatting

Formatting Description
text literal values

<text>

value substitution

Transaction: validate affiliation

To validate an end-user’s affiliation with an institution you must be registered with the InAcademia service and have a valid client id at the OP, see Registration Your Service.

Start of transaction: Authentication Request

A transaction is initiated when an Authentication request is received at the OP. The authentication request is sent by redirecting the end-user to:

Implicit Flow: <inacademia_base>/InAcademia/authorization?nonce=<nonce>&state=<state>&redirect_uri=<redirect_uri>&response_type=id_token&client_id=<client_id>&scope=<scope>

Code: <inacademia_base>/InAcademia/authorization?nonce=<nonce>&state=<state>&redirect_uri=<redirect_uri>&response_type=code&client_id=<client_id>&scope=<scope>

Code with PKCE: <inacademia_base>/InAcademia/authorization?nonce=<nonce>&state=<state>&redirect_uri=<redirect_uri>&response_type=code&code_challenge=<challenge>&code_challenge_method=S256&client_id=<client_id>&scope=<scope>

InAcademia endpoints:

Discovery endpoint: https://op.srv.inacademia.org/.well-known/openid-configuration

Authorization Endpoint: https://op.srv.inacademia.org/InAcademia/authorization

OIDCProvider Issuer: https://op.srv.inacademia.org

All parameters are described in Authentication request. Documentation of the authentication request can be found in the section of the specs about Authentication using the Authorization Code Flow.

Note: Because of the redirect, the request is made by a client (typically a web-browser), and the response is delivered in the fragment identifier of the given redirect URI (see below).

End of transaction: Redirect URI

If the transaction succeeds, an ID Token (encoded as a JWT) will be returned. The ID Token should then be parsed running in the browser at the redirect URI.

Documentation of the response to a successful authentication can be found in the specs section on Successful authentication request.

Registration with the InAcademia service

Please see https://inacademia.org/registering-your-service/

Supported operations

OpenID Provider Configuration

To get the provider configuration of the InAcademia provider, the RP should make the following request:

GET /.well-known/openid-configuration HTTP/1.1
Host: <inacademia_base>

The response will be a JSON document containing, for example, the authorization endpoint (where to direct the authorization request to validate the end-users affiliation).

Full documentation of the provider configuration exchange can be found in OpenID Connect Discovery.

Affiliation validation

Authentication request

The authentication should be directed to:

<inacademia_base>/authorization

The following parameters are allowed in the authentication request (any others will just be ignored):

Table: OIDC Parameter Names

Parameter name Value/description State
response_type code (recommended) or id_token (currently supported but scheduled for deprecation) Required
client_id

<client_id>

Required
scope See Scope Mapping table below. Required
redirect_uri URL to send response to, must be previously registered with the InAcademia service. Required
nonce opaque string to associate the client sessions with the issued ID Token. Required
state opaque string to maintain state between your RP and the InAcademia OP; the state value is returned to the merchant RP in the case of any error scenario. A unique value per user session is advised. Recommended
claims Any additional claims that should be returned in the id token (or from the userinfo endpoint when code flow is used). Optional
aarc_idp_hint URL-encoded entityID to indicate which is the Home Organization of an end user with the intent to skip the discovery service. Introduced in Q2-2022. Optional
idp_hint opaque string to indicate which is the Home Organization of an end user with the intent to skip the discovery service. Scheduled for deprecation 31st August 2022. Optional

Supported Scopes

The type of affiliation to be validated for the transaction must be specified in the scope of the authentication request. There are two categories of scopes allowed:

  • Affiliation: what type of affiliation should be validated?
  • Identifier: what type of identifier is requested (persistent, to be able to identify returning users subsequent to the first validation, provided that the relevant attributes are supported and released by the institution, or transient, unique for each validation transaction)?

A valid scope string must fulfil the following:

  • Exactly one value from the affiliation category of scopes must be specified.
  • At most one value from the identifier category may be specified. If no value from the identifier category is specified, transient (see below table for description) is assumed.

Hence, the affiliation scope is required while both identifier and other scopes are optional. Any ambiguous or unsupported scope strings will be immediately rejected by the InAcademia service (refer to the Possible Errors Section below).

The table below contains all values, grouped by category, allowed in the scope string:

Table: Scope Mapping

Scope Description
Affiliation student Is the end-user a student at the institution?
faculty+staff Is the end-user a teacher/researcher (faculty) or a worker (other than teacher/researcher, staff) at the institution?
employee Is the end-user an employee at the institution?
member This person is either a student, faculty, staff or employee at the institution. This scope will also return users that are configured with only the ‘member’ affiliation.
Identifier persistent Unique identifier, persistent for this end-user subsequent to the first validation, provided that the relevant attributes are supported and released by the institution, and where the validity of the identifier depends on the institution maintaining its persistence.
transient Transient identifier, which is unique for each transaction.

Additional claims

To request additional claims about the end user, the claims parameter can be specified in the authentication request, see Claims Parameter in Authentication request

The additional claims that can be requested can be seen in the following table:

Table: Additional Claims

Claim Value Description
re-use detection A list of unique identifiers (an opaque string) Intends to detect abuse of one-time offers
country (deprecated) Not required (empty) The country of the users home institution
domain (deprecated) Not required (empty) The domain name of the users home institution
idp_hint (to be deprecated)  "idp_hint": {"value": "852a417caadd2225496b583962c432ec8b84212e"} Value is an opaque string to indicate which is the Home Organization of an end user. Json object in the specified format. Deprecated 31 August 2022.

Identity Provider Hinting

IdP_hinting is an extension to the InAcademia service that intends to assist merchants who are keen to minimise 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.

An RP registered with the InAcademia service can create automatic redirects between an internally hosted database of institution names and specified institutions that are inside the scope of the InAcademia service by including a valid and correctly encoded IdP Hint in the Authorization Request to InAcademia. InAcademia will redirect the user to its Home Organization directly instead of prompting them to select an institution from a Discovery Service UI. This has the added benefit of allowing merchants to constrain users to choose from IdPs on a country-by-country basis, and/or to target specific institutions or subsets of institutions with specific campaigns.

The list of institutions for IdP hinting is based on:

  • the members of the eduGAIN Interfederation, plus
  • entities only available nationally where InAcademia is registered in that national federation.

Institutions will sometimes change the technical infrastructure upon which InAcademia relies to validate a user, which might be a change to the entityID registered in eduGAIN or when the name of the institution changes. In such cases the  merchant must update the IdP hint information accordingly. While these changes are not frequent on a per institution level, it is nevertheless recommended to directly consume the JSON feeds, and to make a dynamic list of institutions from which your  users can select using the JSON feeds provided, to automatically refresh any mapping towards the JSON feeds on at least a nightly basis or to monitor the data in order to incorporate any updates into the merchant service on a daily basis. If the data is not monitored or consumed to support live updates to the selectable institutions, and the institutions makes a change to its entityID, requests sent to that IdP will contain a stale hint.

In the event that an invalid or stale IdP hint is used in the Authentication Request, InAcademia will return the user to the specified redirect_uri.

The IdP Hint Assertion feature helps merchants verify that the validation returns from the institution used to initiate the validation.

RPs indicate they know the Home Organization of the end user by using the aarc_idp_hint request parameter, as introduced at v3.3.0 and a valid IdP Hint.

The validation response will assert that the user has been validated as an affiliate of the specific institution that was the subject of the request (feature name ‘IdP Hint Assertion’. This feature adds a further level of validation and can mitigate against exploitation by other users or third parties, ensuring that the user subject to the validation is not only affiliated with academia, but is affiliated with a specific institution.

For example:

<inacademia_base>/InAcademia/authorization?nonce=<nonce>&state=<state>&redirect_uri=<redirect_uri>&response_type=id_token&client_id=<client_id>&scope=<scope>&aarc_idp_hint=<aarc_idp_hint>

InAcademia provides and maintains a mapping between aarc_idp_hint values and Display Names of Home Organisations (available here).

Note that prior to v3.3.0 the idp_hint parameter was supported, which required the hint to be formatted as a sha1 hash. The idp_hint and sha1 hash-based approach is no longer supported for new customers of InAcademia and will be deprecated 31st August 2022.

Transaction success

If the transaction succeeds an ID Token and the state (if included in the initial authentication request) will be returned in the fragment identifier part of the redirect URI (see Successful authentication request). The ID Token is a JSON Web Token, containing a JSON document with all returned claims, see the table below. The id token should be inspected and validated, see ID Token Validation. A public key is required by the RP, and many OIDC frameworks fetch the public key by default, however, it’s possible to get the public key from the .well-known endpoint of the test or production platform. The .well-known endpoint contains the jwks_uri which contains the public key. 

Table: The ID_token

Claim Description Example
aud list which must contain your client id, otherwise the id token must be rejected
auth_time when the end-user authenticated at its institution
at_hash Used for Access Token Validation When using the Authorization Code Flow, if the ID Token contains an at_hash Claim, the Client MAY use it to validate the Access Token in the same manner as for the Implicit Flow, as defined in Section 3.2.2.9, but using the ID Token and Access Token returned from the Token Endpoint.
exp the id token's expiration date, approximately 60 minutes after the end-user authenticated at its institution
iat when the id token was issued
iss issuer identifier of the InAcademia service, must exactly match inacademia_base
nonce if your initial authentication request contained a nonce, this value should be matched exactly with that
sub identifier of the transaction/end-user. If a transient identifier was requested this value will be unique per transaction. If a persistent identifier was requested this value will be unique per end-user valid subsequent to the first validation, provided that the relevant attributes are supported and released by the institution, and where the validity of the identifier depends on the institution maintaining its persistence.
requested_scopes a json object containing all the scopes that the RP originally requested in the authentication request. The client MUST verify that the scopes contained in requested_scopes are exactly the same as those originally requested, otherwise the id token must be rejected. An example of requested scopes in the id token is as follows :  "requested_scopes": {"values": ["openid","persistent","student"]}
requested_claims all the claims that the RP originally requested in the authentication request. The client MUST verify that the claims contained in requested_claims are exactly the same as those originally requested, otherwise the id token must be rejected.
ID Token claims

The ID Token may also contain additional claims. The claims in the table Additional (optional) ID Token claims below will be included if:

  • you are allowed to obtain them
  • they were requested in the initial authentication request (see Additional Claims section above)
  • the institution provides them to the InAcademia service

Table: Additional (optional) ID token claims

Claim Description Example
reuse_detection A list of unique identifiers (an opaque string)
Implicit claims A transaction ID and the confirmed scopes are returned in as claims. OIDC_CLAIM_returned_scopes: {"values": ["openid", "persistent", "member"]} OIDC_CLAIM_transaction_id: 29b21fc5-462e-4d4a-a752-ccf7be0e65df
country (deprecated) country code (ISO_3166-1_alpha-3) of the institution
domain (deprecated) domain name of the institution
idp_hint Json object in the example format (deprecated at 31 August 2022)  "idp_hint": {"value": "852a417caadd2225496b583962c432ec8b84212e"}


Please note that in the case of Authorization Code Flow (response_type=code),  any of the claims listed in the above table can be requested as part of the userinfo response by specifying userinfo claims in the Authorzation Request.

Transaction fail

A transaction will only be started if:

  1. the RP is registered with the InAcademia service and has a valid client id
  2. the Redirect URI, specified in the authentication request, is among the URI’s given when registering with the InAcademia service
  3. the authentication request contains the valid client id
  4. the scope specified in the authentication request is valid
  5. the response type is support and valid only code (recommended) and id_token (to be deprecated) are supported.
  6. the claim specified is supported
  7. the entityID can be resolved

If 1. or 2. is not satisfied, no response will be sent to the RP, instead an error will be displayed to the end user. If 3. to 7. are not satisfied, an error response will be sent to the RP (see Possible errors table below for error codes). The error response will be encoded in the fragment part of the redirect URI:

<redirect_uri>#error=<error_code>&error_description=<error_description>

where the error_description is optional and therefore might be missing.

The transaction will fail if:

  • the end-user wants to validate its affiliation with an unknown institution (for the InAcademia service) or an institution not part of eduGAIN
  • the end-user was not authenticated at the selected institution
  • the institution did not provide enough information to the InAcademia service to validate the affiliation
  • the end-user did not give consent to release the necessary information

If the transaction fails an error code, and where practicable, an error description will be returned in the fragment part of the redirect URI (in the same way as described above).

Possible errors

Table: Error Codes

Error code Reasons
access_denied end-user unauthorized, unknown or non-eduGAIN institution, the affiliation could not be validated, user denied consent
invalid_scope invalid scope specified in the authentication request
invalid_request invalid, mismatching or missing redirect_URI, invalid response_type or unsupported response_type in the authorisation request, or invalid authorization code was provided while invoking the token endpoint
unauthorised_client invalid or missing client_id in the authentication request
invalid_grant Missing grant_type while invoking the token endpoint
invalid_client Invalid client credentials were provided while invoking the token endpoint
invalid_token Invalid access token was provided while invoking the userinfo endpoint

See ‘InAcademia Functional Flow With Errors’ for more detailed information concerning the possible error flows and error descriptions returned. It is strongly recommended that the client is configured to gracefully handle all scenarios.

Skip to content