Changes for page Permissions Configuration

Last modified by colinw on 2021/09/10 23:34

From version 11.1
edited by colinw
on 2014/11/10 23:01
Change comment: There is no comment for this version
To version 16.3
edited by colinw
on 2021/09/10 23:34
Change comment: Update document after refactoring.

Summary

Details

Page properties
Parent
... ... @@ -1,0 +1,1 @@
1 +iSymphony Developer Documentation.REST API Documentation.Configuration API.WebHome
Content
... ... @@ -1,19 +1,30 @@
1 +{{layout}}
2 +{{layout-section ac:type="two_right_sidebar"}}
3 +{{layout-cell}}
1 1  {{warning}}
2 2  This page is currently being written. Although the information below is probably accurate, it may not be complete or may have errors.
3 3  {{/warning}}
4 4  
5 -
8 +{{info}}
9 +The information on this page applies to **iSymphony 3.1+**.
10 +{{/info}}
6 6  
7 -==== **//On this page~://** ====
12 += (% style="color: rgb(0,0,0);" %)Description(%%) =
8 8  
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}}
9 9  
17 +{{layout-cell}}
18 +{{panel title="On this page:"}}
10 10  
11 -{{toc maxLevel="2" indent="1"/}}
12 12  
13 -= Description =
21 +{{toc maxLevel="2" indent="1"/}}
22 +{{/panel}}
23 +{{/layout-cell}}
24 +{{/layout-section}}
14 14  
15 -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.
16 -
26 +{{layout-section ac:type="single"}}
27 +{{layout-cell}}
17 17  === Overview ===
18 18  
19 19  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.
... ... @@ -20,21 +20,35 @@
20 20  
21 21  === Defaults ===
22 22  
23 -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.
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.
24 24  
25 25  === **Exceptions** ===
26 26  
27 -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. There are a few special cases.
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.
28 28  
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 +
29 29  = Root Resource Paths =
30 30  
31 31  {{code}}
32 32  communication_manager/api/resource/core/{core_server_id}/permissions
33 -communication_manager/api/resource/core/getBySlug/{core_server_slug}/permissions
34 34  {{/code}}
35 35  
36 36  = JSON Representation =
37 37  
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 +
38 38  {{code title="PermissionConfig" language="js"}}
39 39   {
40 40   "key": "cellPhoneOriginateTo",
... ... @@ -95,14 +95,35 @@
95 95  
96 96  |=(% colspan="2" %)(% colspan="2" %)
97 97  (((
98 -{{{communication_manager/api/resource/core/{core_server_id}/permissions/userGroup/{user_group_id}}}}
99 -
100 -{{{communication_manager/api/resource/core/getBySlug/{core_server_slug}/permissions/userGroup/{user_group_id}}}}
123 +communication_manager/api/resource/core/{core_server_id}/permissions
101 101  )))
102 -|(% class="highlight-grey" data-highlight-colour="grey" %)(% class="highlight-grey" data-highlight-colour="grey" %)
103 -(((
125 +|=(((
104 104  **Description**
105 105  )))|(((
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 +(((
106 106  Retrieves permissions for the user group identified by the {user_group_id} path parameter.
107 107  
108 108  **Parameters**:
... ... @@ -115,21 +115,18 @@
115 115  
116 116  * 404 'No user group exists with that id.': Returned if the provided user_group_id does not match a user group in the system.
117 117  )))
118 -|(% class="highlight-grey" data-highlight-colour="grey" %)(% class="highlight-grey" data-highlight-colour="grey" %)
164 +|=(% colspan="1" %)(% colspan="1" %)
119 119  (((
120 -**GET**
121 -)))|(((
166 +GET
167 +)))|(% colspan="1" %)(% colspan="1" %)
168 +(((
122 122  Retrieves all permissions defined for the user group.
123 123  )))
124 -
125 125  |=(% colspan="2" %)(% colspan="2" %)
126 126  (((
127 127  {{{communication_manager/api/resource/core/{core_server_id}/permissions/userGroup/{user_group_id}/{key}}}}
128 -
129 -{{{communication_manager/api/resource/core/getBySlug/{core_server_slug}/permissions/userGroup/{user_group_id}/{key}}}}
130 130  )))
131 -|(% class="highlight-grey" data-highlight-colour="grey" %)(% class="highlight-grey" data-highlight-colour="grey" %)
132 -(((
175 +|=(((
133 133  **Description**
134 134  )))|(((
135 135  Retrieves or updates a specific permission for a user group.
... ... @@ -148,10 +148,11 @@
148 148  
149 149  * 404 'No user group exists with that id.': Returned if the provided user_group_id does not match a user group in the system.
150 150  )))
151 -|(% class="highlight-grey" data-highlight-colour="grey" %)(% class="highlight-grey" data-highlight-colour="grey" %)
194 +|=(% colspan="1" %)(% colspan="1" %)
152 152  (((
153 153  **GET**
154 -)))|(((
197 +)))|(% colspan="1" %)(% colspan="1" %)
198 +(((
155 155  Retrieves a specific permission for the user group.
156 156  
157 157  **Errors**:
... ... @@ -158,10 +158,11 @@
158 158  
159 159  * 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.
160 160  )))
161 -|(% class="highlight-grey" data-highlight-colour="grey" %)(% class="highlight-grey" data-highlight-colour="grey" %)
205 +|=(% colspan="1" %)(% colspan="1" %)
162 162  (((
163 163  **PUT**
164 -)))|(((
208 +)))|(% colspan="1" %)(% colspan="1" %)
209 +(((
165 165  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.
166 166  
167 167  **Errors**:
... ... @@ -169,7 +169,7 @@
169 169  * 412 'You must specify a key for a permission.': Returned if the permission definition that is supplied does not have a key defined.
170 170  * 412 'You cannot specify an inherited permission. Remove the permission instead.': Returned if the inherited flag of the permission definition is set to true.
171 171  )))
172 -|(% class="highlight-grey" colspan="1" data-highlight-colour="grey" %)(% class="highlight-grey" colspan="1" data-highlight-colour="grey" %)
217 +|=(% colspan="1" %)(% colspan="1" %)
173 173  (((
174 174  **DELETE**
175 175  )))|(% colspan="1" %)(% colspan="1" %)
... ... @@ -180,14 +180,11 @@
180 180  
181 181  * 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.
182 182  )))
183 -
184 184  |=(% colspan="2" %)(% colspan="2" %)
185 185  (((
186 186  {{{communication_manager/api/resource/core/{core_server_id}/permissions/user/{user_id}}}}
187 -
188 -{{{communication_manager/api/resource/core/getBySlug/{core_server_slug}/permissions/user/{user_id}}}}
189 189  )))
190 -|(% class="highlight-grey" data-highlight-colour="grey" %)(% class="highlight-grey" data-highlight-colour="grey" %)
232 +|=(% class="highlight-grey" data-highlight-colour="grey" %)(% class="highlight-grey" data-highlight-colour="grey" %)
191 191  (((
192 192  **Description**
193 193  )))|(((
... ... @@ -203,20 +203,17 @@
203 203  
204 204  * 404 'No user exists with that id.': Returned if the provided user_id does not match a user in the system.
205 205  )))
206 -|(% class="highlight-grey" data-highlight-colour="grey" %)(% class="highlight-grey" data-highlight-colour="grey" %)
248 +|=(% class="highlight-grey" data-highlight-colour="grey" %)(% class="highlight-grey" data-highlight-colour="grey" %)
207 207  (((
208 208  **GET**
209 209  )))|(((
210 210  Retrieves all permissions defined for the user.
211 211  )))
212 -
213 213  |=(% colspan="2" %)(% colspan="2" %)
214 214  (((
215 215  {{{communication_manager/api/resource/core/{core_server_id}/permissions/user/{user_id}/{key}}}}
216 -
217 -{{{communication_manager/api/resource/core/getBySlug/{core_server_slug}/permissions/user/{user_id}/{key}}}}
218 218  )))
219 -|(% class="highlight-grey" data-highlight-colour="grey" %)(% class="highlight-grey" data-highlight-colour="grey" %)
258 +|=(% class="highlight-grey" data-highlight-colour="grey" %)(% class="highlight-grey" data-highlight-colour="grey" %)
220 220  (((
221 221  **Description**
222 222  )))|(((
... ... @@ -236,7 +236,7 @@
236 236  
237 237  * 404 'No user exists with that id.': Returned if the provided user_id does not match a user in the system.
238 238  )))
239 -|(% class="highlight-grey" data-highlight-colour="grey" %)(% class="highlight-grey" data-highlight-colour="grey" %)
278 +|=(% class="highlight-grey" data-highlight-colour="grey" %)(% class="highlight-grey" data-highlight-colour="grey" %)
240 240  (((
241 241  **GET**
242 242  )))|(((
... ... @@ -246,7 +246,7 @@
246 246  
247 247  * 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.
248 248  )))
249 -|(% class="highlight-grey" data-highlight-colour="grey" %)(% class="highlight-grey" data-highlight-colour="grey" %)
288 +|=(% class="highlight-grey" data-highlight-colour="grey" %)(% class="highlight-grey" data-highlight-colour="grey" %)
250 250  (((
251 251  **PUT**
252 252  )))|(((
... ... @@ -257,11 +257,10 @@
257 257  * 412 'You must specify a key for a permission.': Returned if the permission definition that is supplied does not have a key defined.
258 258  * 412 'You cannot specify an inherited permission. Remove the permission instead.': Returned if the inherited flag of the permission definition is set to true.
259 259  )))
260 -|(% class="highlight-grey" colspan="1" data-highlight-colour="grey" %)(% class="highlight-grey" colspan="1" data-highlight-colour="grey" %)
299 +|=(% class="highlight-grey" data-highlight-colour="grey" %)(% class="highlight-grey" data-highlight-colour="grey" %)
261 261  (((
262 262  **DELETE**
263 -)))|(% colspan="1" %)(% colspan="1" %)
264 -(((
302 +)))|(((
265 265  Clears the specific permission definition for the user.
266 266  
267 267  **Errors**:
... ... @@ -269,28 +269,39 @@
269 269  * 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.
270 270  )))
271 271  
310 +
311 +
272 272  = Curl Examples =
273 273  
274 -=== Get ===
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}}
275 275  
318 +=== (% style="color: rgb(0,0,0);" %)Get all defined permissions for the 'All Users' group(%%) ===
319 +
276 276  {{code language="bash"}}
277 - 
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
278 278  {{/code}}
279 279  
280 -=== (% style="color: rgb(0,0,0);" %)Update(%%) ===
324 +=== Get all defined permissions for a specific user ===
281 281  
282 -{{code language="bash"}}
283 - 
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
284 284  {{/code}}
285 285  
286 -=== Add ===
330 +=== (% style="color: rgb(0,0,0);" %)Deny the 'passwordChange' permission for the above user(%%) ===
287 287  
288 288  {{code language="bash"}}
289 - 
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
290 290  {{/code}}
291 291  
292 -=== Delete ===
336 +=== Remove the 'passwordChange' permission for the above user ===
293 293  
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 +
294 294  {{code language="bash"}}
295 - 
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
296 296  {{/code}}
343 +{{/layout-cell}}
344 +{{/layout-section}}
345 +{{/layout}}