Wiki source code of Accreditation workflow

Last modified by allan on 2020/03/10 13:52
Hide last authors
allan 9.1 1 (% class="wikigeneratedid" %)
2 (((
3 {{warning}}
4 This is a draft
5 {{/warning}}
6 )))
7
allan 9.2 8 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.
allan 2.1 9
allan 15.1 10 == Definitions ==
allan 2.1 11
allan 15.1 12 === Accreditation ===
allan 9.11 13
allan 9.12 14 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).
allan 9.11 15
16 Therefore, an accreditation is defined by:
17
18 * a name
19 * a set of accessible features
20 * a set of granters
21
allan 15.1 22 === Accreditation request ===
allan 9.11 23
allan 9.34 24 An accreditation request is defined by:
25
allan 9.11 26 * a requester
27 * a granter
28 * a status (pending, accepted or denied)
29 * an accreditation
30 * a set of timed events (creation, modification, deletion...)
31
allan 15.1 32 == Stakeholder needs ==
allan 9.2 33
allan 15.1 34 === R1 - User registration ===
allan 9.2 35
36 As a potential user, I want to be able to register to access the protected services of the Collaboratory ecosystem.
37
allan 15.1 38 === R2 - Protecting services ===
allan 9.2 39
40 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.
41
allan 15.1 42 === R3 - Requesting accreditation ===
allan 9.2 43
allan 9.34 44 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.
allan 9.2 45
allan 15.1 46 == Proposed implementation ==
allan 9.11 47
allan 15.1 48 === System components ===
allan 9.2 49
allan 15.4 50 [[**Keycloak**>>https://iam.ebrains.eu]] is the identity and authentication manager (IAM) application. It is used for single sign on and stores user information in a profile.
allan 2.1 51
allan 9.34 52 [[**PLUS**>>https://plus.humanbrainproject.eu/]] 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>>https://www.keycloak.org/docs-api/6.0/rest-api/index.html]].
allan 2.1 53
allan 15.1 54 === Accreditation levels ===
allan 9.34 55
56 There are anonymous users and three levels of accredited users.
57
58 * **hbp-guest:** HBP guests are users that are registered and have provided an email which belongs to a list of recognized institutions.
59 * **hbp-member:** HBP members are members that are accredited and recognized by an acting official as having a contract tied to the HBP.
60 * **hbp-partner:** HBP partners are members that are accredited and recognized as having a contract with a partnering project.
61
allan 11.1 62 Accreditation levels are represented in KeyCloak by [[roles>>https://www.keycloak.org/docs/latest/server_admin/index.html#client-roles]] in a dedicated //accreditation// [[client>>https://www.keycloak.org/docs/latest/server_admin/index.html#oidc-clients]].
allan 9.34 63
64 The level of accreditation of a user is protected behind an //accreditation// [[scope>>https://www.keycloak.org/docs/latest/server_admin/index.html#_client_scopes]].
65
66 When a client [[gets an access token>>https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth]] or calls the [[userinfo endpoint>>https://openid.net/specs/openid-connect-core-1_0.html#UserInfo]] with the //accreditation// scope, an //accreditation// [[claim>>https://openid.net/specs/openid-connect-core-1_0.html#Claims]] is returned with a list of the current user accreditation levels:
67
68 {{code language="json"}}
69 {
70 "sub": "47503e8e-76ed-46ff-9acf-39bee8e0e782",
71 "email_verified": true,
72 "roles": {
73 "accreditation": ["hbp-member"],
74 ...
75 },
76 ...
77 }
78 {{/code}}
79
allan 15.1 80 === Registration ===
allan 9.34 81
allan 9.35 82 The initial step is conducted by the new user, which happens in Keycloak:
83
84 1. the user visits the Keycloak registration page through a provided link in a documentation or the `Register` button on the login form
85 1. the user provides an email, username, name, and optional fields
86 1. 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.
87 1. the user must agree to the Terms & Conditions
88 1. the user account is created and added to the **HBP Guest** group which has the `hbp-guest` role from the `accreditation` client
89
allan 15.1 90 === Requesting a higher level of accreditation ===
allan 9.35 91
allan 15.1 92 ==== workflow ====
allan 9.35 93
allan 9.36 94 To obtain a higher level of accreditation, a user:
95
96 1. goes to the accreditation module of PLUS
97 1. is presented a list of accreditations she can request
98 1. selects an accreditation she does not have
allan 10.1 99 1. is presented a list of units she can be added to
100 1. selects one or several units
allan 9.36 101 1. validates the request
102
allan 10.1 103 A granter of the accreditation for the given unit(s):
allan 9.36 104
105 1. receives an email with:
106 (% start="1" style="list-style-type:lower-alpha" %)
allan 10.1 107 11. a description of the request (who is the user, to which unit she wants to be added)
allan 9.36 108 11. a link to directly approve the request
109 11. a link to directly reject the request
110 11. a link to all pending requests
allan 10.1 111 1. can accept or deny the request if she is the first one for the given unit
allan 9.36 112
allan 15.1 113 ==== technical details ====
allan 9.36 114
allan 10.1 115 An accreditation role in the //accreditation// client contains a unit attribute to specify which unit a user can select:
allan 9.36 116
allan 9.37 117 {{code language="json"}}
118 "accreditation-client": {
119 "roles": {
120 "hbp-member": {
allan 10.1 121 "units": [
allan 9.37 122 "hbp/sga2/sp1",
123 "hbp/sga2/sp2",
124 "hbp/sga2/sp3",
125 ...
126 ]
127 }
128 }
129 }
130 {{/code}}
131
132 (% class="wikigeneratedid" %)
allan 10.1 133 The units contains attributes to specify who can grant accreditations:
allan 9.37 134
135 {{code language="json"}}
136 {
137 "hbp/sga2/sp1": {
allan 10.1 138 "granter-units": ["hbp/sga2/sp1/manager"],
allan 9.37 139 "granter-users": ["jdoe"]
140 },
141 "hbp/sga2/sp2": {
allan 10.1 142 "granter-units": ["hbp/sga2/sp2/manager"],
allan 9.37 143 "granter-users": ["stefan"]
144 },
145 ...
146 }
147 {{/code}}
148
allan 15.1 149 === Mapping service permissions to accreditation levels ===
allan 2.1 150
allan 11.1 151 Each service provider lists its service features and specifies to which accreditation levels they are available, for example:
allan 2.1 152
allan 11.1 153 (% style="height:112px; width:703px" %)
154 |=(% style="width: 149px;" %)Feature id|=(% style="width: 241px;" %)Description|=(% style="width: 93px;" %)hbp-guest|=(% style="width: 113px;" %)hbp-member|=(% style="width: 104px;" %)hbp-partner
155 |(% style="width:149px" %)login|(% style="width:241px" %)User can access the Collaboratory|(% style="width:93px" %)✅|(% style="width:113px" %)✅|(% style="width:104px" %)✅
156 |(% style="width:149px" %)create-collab|(% style="width:241px" %)User can create collabs|(% style="width:93px" %)❌|(% style="width:113px" %)✅|(% style="width:104px" %)✅
157 |(% style="width:149px" %)...|(% style="width:241px" %) |(% style="width:93px" %) |(% style="width:113px" %) |(% style="width:104px" %)
allan 2.1 158
allan 11.1 159 (% class="wikigeneratedid" %)
160 The features are created as [[roles>>https://www.keycloak.org/docs/latest/server_admin/index.html#client-roles]] in the service client and mapped to accreditation levels through [[role composition>>https://www.keycloak.org/docs/latest/server_admin/index.html#_composite-roles]], meaning that when a user gets an accreditation level, she also gets the linked client roles.
allan 2.1 161
allan 11.1 162 (% class="wikigeneratedid" %)
163 The service provider can then check the permissions coming from the user access token to protect his service:
allan 2.1 164
allan 11.1 165 {{code language="json"}}
166 {
167 "sub": "47503e8e-76ed-46ff-9acf-39bee8e0e782",
168 "email_verified": true,
169 "roles": {
170 "accreditation": ["hbp-member"],
171 "collaboratory": ["login", "create-collab"]
172 ...
173 },
174 ...
175 }
176 {{/code}}
allan 2.1 177
allan 15.1 178 === Revocation ===
allan 2.1 179
180 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.
181
allan 15.1 182 === Administrators ===
allan 2.1 183
allan 2.2 184 Who manages the administrators?