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.
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:
"sub": "47503e8e-76ed-46ff-9acf-39bee8e0e782",
"email_verified": true,
"roles": {
"accreditation": ["hbp-member"],
...
},
...
}
Registration
The initial step is conducted by the new user, which happens in Keycloak:
- the user visits the Keycloak registration page through a provided link in a documentation or the `Register` button on the login form
- the user provides an email, username, name, and optional fields
- 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.
- the user must agree to the Terms & Conditions
- 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:
- goes to the accreditation module of PLUS
- is presented a list of accreditations she can request
- selects an accreditation she does not have
- is presented a list of units she can be added to
- selects one or several units
- validates the request
A granter of the accreditation for the given unit(s):
- receives an email with:
- a description of the request (who is the user, to which unit she wants to be added)
- a link to directly approve the request
- a link to directly reject the request
- a link to all pending requests
- 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:
"roles": {
"hbp-member": {
"units": [
"hbp/sga2/sp1",
"hbp/sga2/sp2",
"hbp/sga2/sp3",
...
]
}
}
}
The units contains attributes to specify who can grant accreditations:
"hbp/sga2/sp1": {
"granter-units": ["hbp/sga2/sp1/manager"],
"granter-users": ["jdoe"]
},
"hbp/sga2/sp2": {
"granter-units": ["hbp/sga2/sp2/manager"],
"granter-users": ["stefan"]
},
...
}
Accreditations
Accreditations are a way of recognizing that a user has membership with a group that is recognized in the HBP stucture as a representative of an institution. Thus, a user must be part of a group such as an SP in SGA2, and a member of an institution, such as EPFL.
- Accreditations are represented as a group. NOTE: see footnote for technical discussion. This might not be sufficient.
Workflow
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?
Notes
Questions on Keycloak's capabilities
- should we store accreditations there? Keycloak has a KV storage on users. How do we represent the accreditation eg (SP05 + EPFL)? 1 group per accred will make a huge cross product. Or we store it as an attribute on the user: (accred1: SP5, instit1: EPFL) (accred2: SP11, instit2: JULICH) Or we store it in plus.