Wiki source code of Permissions Configuration

Last modified by colinw on 2021/09/10 23:34
Show last authors
1 {{layout}}
2 {{layout-section ac:type="two_right_sidebar"}}
3 {{layout-cell}}
4 {{warning}}
5 This page is currently being written. Although the information below is probably accurate, it may not be complete or may have errors.
6 {{/warning}}
7
8 {{info}}
9 The information on this page applies to **iSymphony 3.1+**.
10 {{/info}}
11
12 = (% style="color: rgb(0,0,0);" %)Description(%%) =
13
14 The Permissions resource provides access to query and define permissions for iSymphony. See the reference information below for details about the REST interactions used to define permissions. The rest of this description is provided to make it easier to understand the various interactions that go into the permission system in iSymphony.
15 {{/layout-cell}}
16
17 {{layout-cell}}
18 {{panel title="On this page:"}}
19
20
21 {{toc maxLevel="2" indent="1"/}}
22 {{/panel}}
23 {{/layout-cell}}
24 {{/layout-section}}
25
26 {{layout-section ac:type="single"}}
27 {{layout-cell}}
28 === Overview ===
29
30 In version 3.0 and previous of iSymphony, permissions were defined for 'permissible' objects in the system - each object that could be controlled via permissions (extensions, queues, other users, etc) would store a list of the users allowed to perform actions on it, and which actions each was allowed to perform. Beginning in version 3.1 of iSymphony, the situation has been reversed, to make it easier to administer permissions and hopefully less confusing. Permissions are defined for each user or user group in the system, in a cascading manner. They are evaluated in order of decreasing specificity, and in the case of a conflicting tie, the action is allowed. This must be considered when using the REST system to define permissions. See the documentation for permissions for more details.
31
32 === Defaults ===
33
34 By default, all users in the system are allowed to perform all actions. Therefore, if a specific permission key has not been defined for a user (either on the user itself, or one of the groups it is a member of), that action should be considered allowed. When defining a permission, the default policy is also allowed, unless the allowed flag is set to false.
35
36 === **Exceptions** ===
37
38 The heart of the permission system lies in the exceptions to the rules. This allows for powerful combinations to be achieved. Generally, the objects defined by their UUIDs in the exceptions field will be allowed to perform an action if the allowed flag is false, and prevented from performing that action if the allowed flag is true. That is, they will follow the opposite of the general policy for that definition.
39
40 === Special Values ===
41
42 There are a few special predefined values that are used by the permission system. They are:
43
44 * All Users Group: The all users group is hard-coded into iSymphony to contain all users. You can use this to set global permissions on the clients. The UUID for the 'All Users' group is 21d97061-ff6a-11e1-a21f-0800200c9a66.
45 * 'Owned' permission target: In many cases, an administrator may want to defined that users only have access to their "own" objects: their user, their extensions, their phone numbers, etc. In this case, setting the permission to 'Deny', with the special exception df41edec-2707-46eb-8b8f-146b01d9b29e will only give users access to their own objects.
46
47 = Root Resource Paths =
48
49 {{code}}
50 communication_manager/api/resource/core/{core_server_id}/permissions
51 {{/code}}
52
53 = JSON Representation =
54
55 {{code title="Core Server Permissions Enabled" language="js"}}
56 {
57 "permissionsEnabled": false
58 }
59 {{/code}}
60
61 Note: the above object is only used to enable or disable permissions. See the page on the core server configuration itself to query the status of the permissions.
62
63 {{code title="PermissionConfig" language="js"}}
64 {
65 "key": "cellPhoneOriginateTo",
66 "allowed": false,
67 "exceptions": [
68 "df41edec-2707-46eb-8b8f-146b01d9b29e"
69 ],
70 "inherited": false
71 }
72 {{/code}}
73
74 |=(((
75 Property
76 )))|=(((
77 Type
78 )))|=(((
79 Description
80 )))
81 |(((
82 {{{key}}}
83 )))|(((
84 String
85 )))|(((
86 The key used for this permission configuration.
87 )))
88 |(% colspan="1" %)(% colspan="1" %)
89 (((
90 allowed
91 )))|(% colspan="1" %)(% colspan="1" %)
92 (((
93 Boolean
94 )))|(% colspan="1" %)(% colspan="1" %)
95 (((
96 Whether the action should be generally allowed or not.
97 )))
98 |(% colspan="1" %)(% colspan="1" %)
99 (((
100 exceptions
101 )))|(% colspan="1" %)(% colspan="1" %)
102 (((
103 Array of Strings (UUID)
104 )))|(% colspan="1" %)(% colspan="1" %)
105 (((
106 The objects defined in the exceptions will be granted or denied access as exceptions to the general rule.
107 )))
108 |(% colspan="1" %)(% colspan="1" %)
109 (((
110 inherited
111 )))|(% colspan="1" %)(% colspan="1" %)
112 (((
113 Boolean
114 )))|(% colspan="1" %)(% colspan="1" %)
115 (((
116 Used internally. Should never be true when using the REST system.
117 )))
118
119 = Resource Paths =
120
121 |=(% colspan="2" %)(% colspan="2" %)
122 (((
123 communication_manager/api/resource/core/{core_server_id}/permissions
124 )))
125 |=(((
126 **Description**
127 )))|(((
128 Specifies whether permissions should be enabled or disabled for the entire core server. When disabled, no permission checks will be performed, so the rest of the settings specified in the permissions system will have no effect. Note that you must have a supported license installed to enable permissions.
129
130 **Parameters**:
131
132 * core_server_id: The UUID of the core server
133
134 **Errors**:
135
136 * 500 'Your license does not support permissions.': Returned if you do not have a license installed, or if your license does not support permissions.
137 )))
138 |=(((
139 PUT
140 )))|(((
141 Sets whether permissions are enabled or disabled globally on the core server.
142 )))
143 |=(% colspan="2" %)(% colspan="2" %)
144 (((
145 {{{communication_manager/api/resource/core/{core_server_id}/permissions/userGroup/{user_group_id}}}}
146 )))
147 |=(% colspan="1" %)(% colspan="1" %)
148 (((
149 Description
150 )))|(% colspan="1" %)(% colspan="1" %)
151 (((
152 Retrieves permissions for the user group identified by the {user_group_id} path parameter.
153
154 **Parameters**:
155
156 * core_server_id: The UUID of the core server.
157 * core_server_slug: The unique identifying slug of the core server.
158 * user_group_id: The UUID of the user group.
159
160 **Errors**:
161
162 * 404 'No user group exists with that id.': Returned if the provided user_group_id does not match a user group in the system.
163 )))
164 |=(% colspan="1" %)(% colspan="1" %)
165 (((
166 GET
167 )))|(% colspan="1" %)(% colspan="1" %)
168 (((
169 Retrieves all permissions defined for the user group.
170 )))
171 |=(% colspan="2" %)(% colspan="2" %)
172 (((
173 {{{communication_manager/api/resource/core/{core_server_id}/permissions/userGroup/{user_group_id}/{key}}}}
174 )))
175 |=(((
176 **Description**
177 )))|(((
178 Retrieves or updates a specific permission for a user group.
179
180 **Parameters**:
181
182 * core_server_id: The UUID of the core server.
183
184 * core_server_slug: The unique identifying slug of the core server.
185
186 * user_group_id: The UUID of the user group.
187
188 * key: The permission key identifying the permission.
189
190 **Errors**:
191
192 * 404 'No user group exists with that id.': Returned if the provided user_group_id does not match a user group in the system.
193 )))
194 |=(% colspan="1" %)(% colspan="1" %)
195 (((
196 **GET**
197 )))|(% colspan="1" %)(% colspan="1" %)
198 (((
199 Retrieves a specific permission for the user group.
200
201 **Errors**:
202
203 * 404 'No permission with that key is defined for that user group.': Returned if there is no permission defined for the user group with that permission key.
204 )))
205 |=(% colspan="1" %)(% colspan="1" %)
206 (((
207 **PUT**
208 )))|(% colspan="1" %)(% colspan="1" %)
209 (((
210 Sets the permission definition for the user group with the specified key. The key defined in the permission definition body must match the key used in the URL.
211
212 **Errors**:
213
214 * 412 'You must specify a key for a permission.': Returned if the permission definition that is supplied does not have a key defined.
215 * 412 'You cannot specify an inherited permission. Remove the permission instead.': Returned if the inherited flag of the permission definition is set to true.
216 )))
217 |=(% colspan="1" %)(% colspan="1" %)
218 (((
219 **DELETE**
220 )))|(% colspan="1" %)(% colspan="1" %)
221 (((
222 Clears the specific permission definition for the user group.
223
224 **Errors**:
225
226 * 404 'No permission with that key is defined for that user group.': Returned if there is no permission defined for the user group with that permission key.
227 )))
228 |=(% colspan="2" %)(% colspan="2" %)
229 (((
230 {{{communication_manager/api/resource/core/{core_server_id}/permissions/user/{user_id}}}}
231 )))
232 |=(% class="highlight-grey" data-highlight-colour="grey" %)(% class="highlight-grey" data-highlight-colour="grey" %)
233 (((
234 **Description**
235 )))|(((
236 Retrieves permissions for the user group identified by the {user_id} path parameter.
237
238 **Parameters**:
239
240 * core_server_id: The UUID of the core server.
241 * core_server_slug: The unique identifying slug of the core server.
242 * user_id: The UUID of the user.
243
244 **Errors**:
245
246 * 404 'No user exists with that id.': Returned if the provided user_id does not match a user in the system.
247 )))
248 |=(% class="highlight-grey" data-highlight-colour="grey" %)(% class="highlight-grey" data-highlight-colour="grey" %)
249 (((
250 **GET**
251 )))|(((
252 Retrieves all permissions defined for the user.
253 )))
254 |=(% colspan="2" %)(% colspan="2" %)
255 (((
256 {{{communication_manager/api/resource/core/{core_server_id}/permissions/user/{user_id}/{key}}}}
257 )))
258 |=(% class="highlight-grey" data-highlight-colour="grey" %)(% class="highlight-grey" data-highlight-colour="grey" %)
259 (((
260 **Description**
261 )))|(((
262 Retrieves or updates a specific permission for a user group.
263
264 **Parameters**:
265
266 * core_server_id: The UUID of the core server.
267
268 * core_server_slug: The unique identifying slug of the core server.
269
270 * user_id: The UUID of the user.
271
272 * key: The permission key identifying the permission.
273
274 **Errors**:
275
276 * 404 'No user exists with that id.': Returned if the provided user_id does not match a user in the system.
277 )))
278 |=(% class="highlight-grey" data-highlight-colour="grey" %)(% class="highlight-grey" data-highlight-colour="grey" %)
279 (((
280 **GET**
281 )))|(((
282 Retrieves a specific permission for the user.
283
284 **Errors**:
285
286 * 404 'No permission with that key is defined for that user.': Returned if there is no permission defined for the user with that permission key.
287 )))
288 |=(% class="highlight-grey" data-highlight-colour="grey" %)(% class="highlight-grey" data-highlight-colour="grey" %)
289 (((
290 **PUT**
291 )))|(((
292 Sets the permission definition for the user with the specified key. The key defined in the permission definition body must match the key used in the URL.
293
294 **Errors**:
295
296 * 412 'You must specify a key for a permission.': Returned if the permission definition that is supplied does not have a key defined.
297 * 412 'You cannot specify an inherited permission. Remove the permission instead.': Returned if the inherited flag of the permission definition is set to true.
298 )))
299 |=(% class="highlight-grey" data-highlight-colour="grey" %)(% class="highlight-grey" data-highlight-colour="grey" %)
300 (((
301 **DELETE**
302 )))|(((
303 Clears the specific permission definition for the user.
304
305 **Errors**:
306
307 * 404 'No permission with that key is defined for that user.': Returned if there is no permission defined for the user with that permission key.
308 )))
309
310
311
312 = Curl Examples =
313
314 {{info}}
315 The server ID in the below examples is 9280cd1c-4ad7-4ed9-ae8a-0648b0b45cf7. You will need to change this to the appropriate ID for your installation, as well as change other IDs.
316 {{/info}}
317
318 === (% style="color: rgb(0,0,0);" %)Get all defined permissions for the 'All Users' group(%%) ===
319
320 {{code language="bash"}}
321 curl --user manager:manag3rpa55word -i -H "Content-Type: application/json" https://127.0.0.1:55050/communication_manager/api/resource/core/9280cd1c-4ad7-4ed9-ae8a-0648b0b45cf7/permissions/userGroup/21d97061-ff6a-11e1-a21f-0800200c9a66
322 {{/code}}
323
324 === Get all defined permissions for a specific user ===
325
326 {{code}}
327 curl --user manager:manag3rpa55word -i -H "Content-Type: application/json" https://127.0.0.1:55050/communication_manager/api/resource/core/9280cd1c-4ad7-4ed9-ae8a-0648b0b45cf7/permissions/user/8a026a93-3201-4554-b993-32576a3b8ea5
328 {{/code}}
329
330 === (% style="color: rgb(0,0,0);" %)Deny the 'passwordChange' permission for the above user(%%) ===
331
332 {{code language="bash"}}
333 curl --user manager:manag3rpa55word -i -H "Content-Type: application/json" -X PUT -d '{"key":"passwordChange","allowed":"false"}' https://127.0.0.1:55050/communication_manager/api/resource/core/9280cd1c-4ad7-4ed9-ae8a-0648b0b45cf7/permissions/user/8a026a93-3201-4554-b993-32576a3b8ea5/passwordChange
334 {{/code}}
335
336 === Remove the 'passwordChange' permission for the above user ===
337
338 Note: this will not prevent the user from changing their password. It will cause the user to inherit the permission of any user groups they are a part of.
339
340 {{code language="bash"}}
341 curl --user manager:manag3rpa55word -i -H "Content-Type: application/json" -X DELETE https://127.0.0.1:55050/communication_manager/api/resource/core/9280cd1c-4ad7-4ed9-ae8a-0648b0b45cf7/permissions/user/8a026a93-3201-4554-b993-32576a3b8ea5/passwordChange
342 {{/code}}
343 {{/layout-cell}}
344 {{/layout-section}}
345 {{/layout}}

Search

Navigation

iSymphony