Wiki source code of Accreditation workflow

Last modified by allan on 2020/03/10 13:52
Show last authors
1 (% class="wikigeneratedid" %)
2 (((
3 {{warning}}
4 This is a draft
5 {{/warning}}
6 )))
7
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.
9
10 == Definitions ==
11
12 === Accreditation ===
13
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).
15
16 Therefore, an accreditation is defined by:
17
18 * a name
19 * a set of accessible features
20 * a set of granters
21
22 === Accreditation request ===
23
24 An accreditation request is defined by:
25
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
32 == Stakeholder needs ==
33
34 === R1 - User registration ===
35
36 As a potential user, I want to be able to register to access the protected services of the Collaboratory ecosystem.
37
38 === R2 - Protecting services ===
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
42 === R3 - Requesting accreditation ===
43
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.
45
46 == Proposed implementation ==
47
48 === System components ===
49
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.
51
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]].
53
54 === Accreditation levels ===
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
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]].
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
80 === Registration ===
81
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
90 === Requesting a higher level of accreditation ===
91
92 ==== workflow ====
93
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
99 1. is presented a list of units she can be added to
100 1. selects one or several units
101 1. validates the request
102
103 A granter of the accreditation for the given unit(s):
104
105 1. receives an email with:
106 (% start="1" style="list-style-type:lower-alpha" %)
107 11. a description of the request (who is the user, to which unit she wants to be added)
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
111 1. can accept or deny the request if she is the first one for the given unit
112
113 ==== technical details ====
114
115 An accreditation role in the //accreditation// client contains a unit attribute to specify which unit a user can select:
116
117 {{code language="json"}}
118 "accreditation-client": {
119 "roles": {
120 "hbp-member": {
121 "units": [
122 "hbp/sga2/sp1",
123 "hbp/sga2/sp2",
124 "hbp/sga2/sp3",
125 ...
126 ]
127 }
128 }
129 }
130 {{/code}}
131
132 (% class="wikigeneratedid" %)
133 The units contains attributes to specify who can grant accreditations:
134
135 {{code language="json"}}
136 {
137 "hbp/sga2/sp1": {
138 "granter-units": ["hbp/sga2/sp1/manager"],
139 "granter-users": ["jdoe"]
140 },
141 "hbp/sga2/sp2": {
142 "granter-units": ["hbp/sga2/sp2/manager"],
143 "granter-users": ["stefan"]
144 },
145 ...
146 }
147 {{/code}}
148
149 === Mapping service permissions to accreditation levels ===
150
151 Each service provider lists its service features and specifies to which accreditation levels they are available, for example:
152
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" %)
158
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.
161
162 (% class="wikigeneratedid" %)
163 The service provider can then check the permissions coming from the user access token to protect his service:
164
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}}
177
178 === Revocation ===
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
182 === Administrators ===
183
184 Who manages the administrators?