Attention: The EBRAINS Wiki and IDM will be down Wednesday 29th October, from 13:00 CEST  for up to 5 minutes due to an upgrade. 


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