The goal is to provide a framework to manage levels of accreditation for users, providing access to different features or quotas based on an auditable level of trust.

1. Definitions
   1. Accreditation
   2. Accreditation request
2. Stakeholder needs
   1. R1 - User registration
   2. R2 - Protecting services
   3. R3 - Requesting accreditation
3. Proposed implementation
   1. System components
   2. Accreditation levels
   3. Registration
   4. Requesting a higher level of accreditation
      1. workflow
      2. technical details
   5. Mapping service permissions to accreditation levels
   6. Revocation
   7. Administrators

Definitions

Accreditation

An accreditation is a way of recognising that a user has a level of trust which is understood and shared across service providers. For all actors to trust a level of accreditation, it must be clearly defined (ie what features can be accessed with which accreditation) and it must be auditable (ie it must be easy to understand how a user gained an accreditation).

Therefore, an accreditation is defined by:

• a name
• a set of accessible features
• a set of granters

Accreditation request

An accreditation request is defined by:

• a requester
• a granter
• a status (pending, accepted or denied)
• an accreditation
• a set of timed events (creation, modification, deletion...)

Stakeholder needs

R1 - User registration

As a potential user, I want to be able to register to access the protected services of the Collaboratory ecosystem.

R2 - Protecting services

As a service provider, I want to be able to restrict or grant access to my service features based on the level of accreditation of the user.

R3 - Requesting accreditation

As a user, I want to be able to request a level of accreditation to gain access to more services which can be accepted or denied by a set of granters.

Proposed implementation

System components

Keycloak is the identity and authentication manager (IAM) application. It is used for single sign on and stores user information in a profile.

PLUS is an internal tool to the HBP where project management is done. It is a Keycloak client and drives the management of certain data stored in Keycloak through Keycloak's API.

Accreditation levels

There are anonymous users and three levels of accredited users.

• hbp-guest: HBP guests are users that are registered and have provided an email which belongs to a list of recognized institutions.
• hbp-member: HBP members are members that are accredited and recognized by an acting official as having a contract tied to the HBP.
• hbp-partner: HBP partners are members that are accredited and recognized as having a contract with a partnering project.

Accreditation levels are represented in KeyCloak by roles in a dedicated accreditation client.

The level of accreditation of a user is protected behind an accreditation scope.

When a client gets an access token or calls the userinfo endpoint with the accreditation scope, an accreditation claim is returned with a list of the current user accreditation levels:

Registration

The initial step is conducted by the new user, which happens in Keycloak:

1. the user visits the Keycloak registration page through a provided link in a documentation or the `Register` button on the login form
2. the user provides an email, username, name, and optional fields
3. the email domain is validated against a whitelist of domains. If the user's email domain is not in the recognized domains, the user is presented with a page specifying how they can request that their institution be added to the list.
4. the user must agree to the Terms & Conditions
5. the user account is created and added to the HBP Guest group which has the `hbp-guest` role from the `accreditation` client

Requesting a higher level of accreditation

workflow

To obtain a higher level of accreditation, a user:

1. goes to the accreditation module of PLUS
2. is presented a list of accreditations she can request
3. selects an accreditation she does not have
4. is presented a list of units she can be added to
5. selects one or several units
6. validates the request

A granter of the accreditation for the given unit(s):

1. receives an email with:
   1. a description of the request (who is the user, to which unit she wants to be added)
   2. a link to directly approve the request
   3. a link to directly reject the request
   4. a link to all pending requests
2. can accept or deny the request if she is the first one for the given unit

technical details

An accreditation role in the accreditation client contains a unit attribute to specify which unit a user can select:

The units contains attributes to specify who can grant accreditations:

Mapping service permissions to accreditation levels

Each service provider lists its service features and specifies to which accreditation levels they are available, for example:

The features are created as roles in the service client and mapped to accreditation levels through role composition, meaning that when a user gets an accreditation level, she also gets the linked client roles.

The service provider can then check the permissions coming from the user access token to protect his service:

Revocation

An accreditation can be revoked by an admin of an accreditation group. The managers are responsible for ensuring the list of validated members is up to date.

Administrators

Who manages the administrators?