Institutions: How to Enable InAcademia
Enabling InAcademia is straightforward: because InAcademia acts as a Service Provider the process is just like interacting with any other Service Provider for your users. Check the prerequisites below, before moving onto the steps. More information follows if you’d like to understand how the flows work. Here, when we say ‘merchant’ we mean a downstream service or customer of the InAcademia service (see table 2 on https://dev.inacademia.org/privacy-statement/).
Prerequisites:
InAcademia always requests the following attributes, and uses them for either of the two different flows* that can be initiated by a merchant as follows:
Transient flow | Persistent flow | |
---|---|---|
Either |
Needed to validate the user’s affiliation | Needed to validate the user’s affiliation |
Any of the following:
|
Discarded | Needed to create a pseudonymised identifier |
Either |
Needed to create a pseudonymised identifier | Needed in order to elicit a response; also needed if the preferred persistent attributes are not released, but otherwise discarded. |
In all cases, the actual value of the identifier returned by the IdP will not be released to the requesting merchant; instead InAcademia will create and return a pseudonymous identifier.
In both flow scenarios, a merchant may request the ‘domain’ claim, constructed from the release of the shacHomeOrganization attribute. This is a ‘sunset’ feature and is to be deprecated. Refer to https://dev.inacademia.org/privacy-statement/ for more information as to which services are using which flow.
In both the persistent and transient scenarios, InAcademia is designed to require all the above attributes because:
- It is a single proxy that operates across many federations, and some persistent attributes are more prevalent in some than in others, but services cannot dynamically request only what is available.
- ePPN and ePTID are to be deprecated, and we’re introducing subject_pairwise in preparation for that.
Step 1:
- Check if your Institution University already releases attributes to InAcademia. We have developed a quick check for InAcademia support to check your current affiliation service, but be sure to test all affiliation types. Note that this only tests the transient identifier scenario.
- If the tests passed, this means your users can be verified with InAcademia's transient flow. If the test does not pass, please continue to steps 2 and 3.
Step 2:
Configure your IdP to release the required attributes to the InAcademia SP (eduGAIN entityID https://dev.inacademia.org/metadata/inacademia-simple-validation.xml) as described in the ‘prerequisites’ section above.
Step 3:
You may need to double check how your national identity federation handles services that want to connect with your users via eduGAIN:
- If your federation is a hub & spoke federation (e.g. SURFconext, WAYF.dk ,…) please ensure that your organisation opts-in for InAcademia and thus allows users to access the InAcademia service. If unsure how to do this, please contact your federation operator https://refeds.org/federations.
- If your federation is a full mesh federation (e.g. SWITCHaai …) please ensure that your IdP contains an attribute release rule for releasing attributes to SPs that support the CoCo, or create a specific release rule for InAcademia
Further information regarding attribute release or privacy are available here and below:
If you are unsure about any of the concepts described please contact us.
*More information:
InAcademia offers two types of validation flow to registered merchants: one outputs a simple validation of the affiliation only, creating a new transient identifier, the other outputs a persistent identifier alongside the validation of the affiliation. Refer to https://dev.inacademia.org/privacy-statement/ for more information as to which services are using which flow.
When the merchant requires a transient identifier:
This flow is used where a merchant is satisfied with a simple transient validation of the user’s affiliation to your institution. InAcademia’s metadata requests both transient and persistent nameID format attributes in order to elicit a response from your IdP, but will discard both. It creates a new transient identifier, and returns that along with confirmation of the user’s affiliation, which is sourced from either:
- eduPersonScopedAffiliation
- eduPersonAffiliation
If your IdP cannot provide eduPersonScopedAffiliation then InAcademia can accept eduPersonAffiliation. The service’s workflow favours the eduPersonScopedAffiliation attribute; whichever it receives, it will construct the response and will discard the rest.
When the merchant requires a persistent identifier:
This flow is used where a merchant needs to ensure that the user is affiliated to your institution, and that the user isn’t attempting to access an offer more than once. InAcademia’s metadata requests both transient and persistent nameID format attributes in order to elicit a response from your IdP. As well as requesting the eduPersonScopedAffiliation an eduPersonAffiliation to confirm the user’s affiliation (and the same rules apply as with the transient flow as far as ePSA and ePA are concerned), InAcademia will also request:
- eduPersonTargetID
- eduPersonPrincipleName
- Pairwise_ID
- Subject_ID
- eduPersonUniqueID
When your IdP supports persistent nameID format, InAcademia will return pseudonymised persistent identifiers to the merchant. Please note that, InAcademia only requires one value in order to return a valid response, but requests multiple values as it cannot signal a preference for the attributes to be released; in that sense, there is no need to release all the required persistent attributes to InAcademia. If your IdP cannot provide eduPersonTargetID, but you can release ePPN or pairwise_id, for example, then we could use any of those. If none of the above are available it will use the persistent SAML nameID attribute. Please note that eduPersonUniqueID will also be deprecated in future.
In the event that a merchant requires a persistent identifier for the use case, but your IdP does not support persistent nameID format, a transient identifier will be returned to the merchant. The merchant may then take an automated decision as to whether or not to allow the user to access the related offer.
In all cases, the actual value returned by the IdP will not be released to the requesting merchant; InAcademia will create a pseudonymous identifier.