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 of 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://github.com/InAcademia/Client-docs

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.

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.
InstitutionThe academic institution the end-user is affiliated with.
TransactionOne 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.
textliteral values
<text>value substitution

Transaction: validate affiliation

To validate an end-users 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:


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 Implicit 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 transacation: Redirect URI

If the transaction succeeds, an ID Token (encoded as a JWT) will be returned in the fragment identifier part of the redirect URI. This can then be parsed using some scripting language in the browser (e.g. Javascript) 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:


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

Parameter nameValue/descriptionState
scopeSee Scope Mapping table belowRequired
redirect_uriURL to send response to, must be previously registered with the InAcademia serviceRequired
nonceopaque string to associate the client sessions with the issued ID TokenRequired
stateopaque string to maintain state between your RP and the InAcademia OPRecommended
claimsAny additional claims that should be returned in the id tokenOptional
idp_hintopaque string to indicate which is the Home Organization of an end user with the intent to skip the discovery service.
Table: Parameters

Supported Scopes

The type of affiliation validation for the transaction is 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, or transient, unique for each validation transaction)?

A valid scope string must fulfill 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 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:

AffiliationstudentIs the end-user a student at the institution?
faculty+staffIs the end-user a teacher/researcher (faculty) or a worker (other than teacher/researcher, staff) at the institution?
employeeIs the end-user an employee at the institution?
memberThis person is either a student, faculty, staff or employee at the institution
IdentifierpersistentPersistent identifier, unique for this end-user.
transientTransient identifier, which is unique for each transaction.
Table: Scope Mapping

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. Only “id_token” is supported as a top-level member and requests.

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

countryNot required (empty)The country of the users home institution
domainNot required (empty)The domain name of the users home institution
idp_hintJson object in the following format: "idp_hint": {"value": "852a417caadd2225496b583962c432ec8b84212e"}Value is an opaque string to indicate which is the Home Organization of an end user with the intent to skip the Discovery Service
Table: Additional Claims

Identity Provider Hinting

If an RP registered with the InAcademia service wants to implement their own Discovery Service, or has another way of pre-identifying the Home Organization of the user, the RP can indicate that fact in the Authorization request to InAcademia. This will result in InAcademia redirecting the user to its Home Organization directly instead of prompting them to select an institution from a Discovery Service UI.

There are two ways that RPs can indicate they know the Home Organization of the end user:

  • idp_hint request parameter (suggested).

For example:

  • idp_hint claim.

For example:


InAcademia provides and maintains a mapping between idp_hint values and Display Names of Home Organizations that is available here.

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.

id token claims

audlist which must contain your client id, otherwise the id token must be rejected
auth_timewhen the end-user authenticated at its institution
expthe id token’s expiration date, approximately 30 minutes after the end-user authenticated at its institution
iatwhen the id token was issued
ississuer identifier of the InAcademia service, must exactly match <inacademia_base>
nonceif your initial authentication request contained a nonce, this value should be matched exactly with that
subidentifier 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
requested_scopesa 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 with the ones 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"]}
Table: The ID_token

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
countrycountry code (ISO_3166-1_alpha-3) of the institution
domaindomain name of the institution
idp_hintJson object in the following format: "idp_hint": {"value": "852a417caadd2225496b583962c432ec8b84212e"}
Table: Additional (optional) ID token claims

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 URL’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 id_token is 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:


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

Error codeReasons
access_deniedend-user unauthorized, unknown or non-eduGAIN institution, the affiliation could not be validated, user denied consent
invalid_scopeinvalid scope specified in the authentication request
invalid_requestinvalid, mismatching or missing redirect_URI, invalid response_type or unsupported response_type in the authorisation request
unauthorised_clientinvalid or missing client_id in the authentication request

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