Changes for page Permissions Configuration

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

From version 15.1
edited by colinw
on 2014/11/11 16:50
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
... ... @@ -35,17 +35,31 @@
35 35  
36 36  === **Exceptions** ===
37 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. 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.
39 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 +
40 40  = Root Resource Paths =
41 41  
42 42  {{code}}
43 43  communication_manager/api/resource/core/{core_server_id}/permissions
44 -communication_manager/api/resource/core/getBySlug/{core_server_slug}/permissions
45 45  {{/code}}
46 46  
47 47  = JSON Representation =
48 48  
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 +
49 49  {{code title="PermissionConfig" language="js"}}
50 50   {
51 51   "key": "cellPhoneOriginateTo",
... ... @@ -106,14 +106,35 @@
106 106  
107 107  |=(% colspan="2" %)(% colspan="2" %)
108 108  (((
109 -{{{communication_manager/api/resource/core/{core_server_id}/permissions/userGroup/{user_group_id}}}}
110 -
111 -{{{communication_manager/api/resource/core/getBySlug/{core_server_slug}/permissions/userGroup/{user_group_id}}}}
123 +communication_manager/api/resource/core/{core_server_id}/permissions
112 112  )))
113 -|(% class="highlight-grey" data-highlight-colour="grey" %)(% class="highlight-grey" data-highlight-colour="grey" %)
114 -(((
125 +|=(((
115 115  **Description**
116 116  )))|(((
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 +(((
117 117  Retrieves permissions for the user group identified by the {user_group_id} path parameter.
118 118  
119 119  **Parameters**:
... ... @@ -126,21 +126,18 @@
126 126  
127 127  * 404 'No user group exists with that id.': Returned if the provided user_group_id does not match a user group in the system.
128 128  )))
129 -|(% class="highlight-grey" data-highlight-colour="grey" %)(% class="highlight-grey" data-highlight-colour="grey" %)
164 +|=(% colspan="1" %)(% colspan="1" %)
130 130  (((
131 -**GET**
132 -)))|(((
166 +GET
167 +)))|(% colspan="1" %)(% colspan="1" %)
168 +(((
133 133  Retrieves all permissions defined for the user group.
134 134  )))
135 -
136 136  |=(% colspan="2" %)(% colspan="2" %)
137 137  (((
138 138  {{{communication_manager/api/resource/core/{core_server_id}/permissions/userGroup/{user_group_id}/{key}}}}
139 -
140 -{{{communication_manager/api/resource/core/getBySlug/{core_server_slug}/permissions/userGroup/{user_group_id}/{key}}}}
141 141  )))
142 -|(% class="highlight-grey" data-highlight-colour="grey" %)(% class="highlight-grey" data-highlight-colour="grey" %)
143 -(((
175 +|=(((
144 144  **Description**
145 145  )))|(((
146 146  Retrieves or updates a specific permission for a user group.
... ... @@ -159,10 +159,11 @@
159 159  
160 160  * 404 'No user group exists with that id.': Returned if the provided user_group_id does not match a user group in the system.
161 161  )))
162 -|(% class="highlight-grey" data-highlight-colour="grey" %)(% class="highlight-grey" data-highlight-colour="grey" %)
194 +|=(% colspan="1" %)(% colspan="1" %)
163 163  (((
164 164  **GET**
165 -)))|(((
197 +)))|(% colspan="1" %)(% colspan="1" %)
198 +(((
166 166  Retrieves a specific permission for the user group.
167 167  
168 168  **Errors**:
... ... @@ -169,10 +169,11 @@
169 169  
170 170  * 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.
171 171  )))
172 -|(% class="highlight-grey" data-highlight-colour="grey" %)(% class="highlight-grey" data-highlight-colour="grey" %)
205 +|=(% colspan="1" %)(% colspan="1" %)
173 173  (((
174 174  **PUT**
175 -)))|(((
208 +)))|(% colspan="1" %)(% colspan="1" %)
209 +(((
176 176  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.
177 177  
178 178  **Errors**:
... ... @@ -180,7 +180,7 @@
180 180  * 412 'You must specify a key for a permission.': Returned if the permission definition that is supplied does not have a key defined.
181 181  * 412 'You cannot specify an inherited permission. Remove the permission instead.': Returned if the inherited flag of the permission definition is set to true.
182 182  )))
183 -|(% class="highlight-grey" colspan="1" data-highlight-colour="grey" %)(% class="highlight-grey" colspan="1" data-highlight-colour="grey" %)
217 +|=(% colspan="1" %)(% colspan="1" %)
184 184  (((
185 185  **DELETE**
186 186  )))|(% colspan="1" %)(% colspan="1" %)
... ... @@ -191,14 +191,11 @@
191 191  
192 192  * 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.
193 193  )))
194 -
195 195  |=(% colspan="2" %)(% colspan="2" %)
196 196  (((
197 197  {{{communication_manager/api/resource/core/{core_server_id}/permissions/user/{user_id}}}}
198 -
199 -{{{communication_manager/api/resource/core/getBySlug/{core_server_slug}/permissions/user/{user_id}}}}
200 200  )))
201 -|(% 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" %)
202 202  (((
203 203  **Description**
204 204  )))|(((
... ... @@ -214,20 +214,17 @@
214 214  
215 215  * 404 'No user exists with that id.': Returned if the provided user_id does not match a user in the system.
216 216  )))
217 -|(% 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" %)
218 218  (((
219 219  **GET**
220 220  )))|(((
221 221  Retrieves all permissions defined for the user.
222 222  )))
223 -
224 224  |=(% colspan="2" %)(% colspan="2" %)
225 225  (((
226 226  {{{communication_manager/api/resource/core/{core_server_id}/permissions/user/{user_id}/{key}}}}
227 -
228 -{{{communication_manager/api/resource/core/getBySlug/{core_server_slug}/permissions/user/{user_id}/{key}}}}
229 229  )))
230 -|(% 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" %)
231 231  (((
232 232  **Description**
233 233  )))|(((
... ... @@ -247,7 +247,7 @@
247 247  
248 248  * 404 'No user exists with that id.': Returned if the provided user_id does not match a user in the system.
249 249  )))
250 -|(% 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" %)
251 251  (((
252 252  **GET**
253 253  )))|(((
... ... @@ -257,7 +257,7 @@
257 257  
258 258  * 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.
259 259  )))
260 -|(% 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" %)
261 261  (((
262 262  **PUT**
263 263  )))|(((
... ... @@ -268,11 +268,10 @@
268 268  * 412 'You must specify a key for a permission.': Returned if the permission definition that is supplied does not have a key defined.
269 269  * 412 'You cannot specify an inherited permission. Remove the permission instead.': Returned if the inherited flag of the permission definition is set to true.
270 270  )))
271 -|(% 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" %)
272 272  (((
273 273  **DELETE**
274 -)))|(% colspan="1" %)(% colspan="1" %)
275 -(((
302 +)))|(((
276 276  Clears the specific permission definition for the user.
277 277  
278 278  **Errors**:
... ... @@ -280,30 +280,38 @@
280 280  * 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.
281 281  )))
282 282  
310 +
311 +
283 283  = Curl Examples =
284 284  
285 -=== 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}}
286 286  
318 +=== (% style="color: rgb(0,0,0);" %)Get all defined permissions for the 'All Users' group(%%) ===
319 +
287 287  {{code language="bash"}}
288 - 
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
289 289  {{/code}}
290 290  
291 -=== Update ===
324 +=== Get all defined permissions for a specific user ===
292 292  
293 -{{code language="bash"}}
294 - 
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
295 295  {{/code}}
296 296  
297 -=== Add ===
330 +=== (% style="color: rgb(0,0,0);" %)Deny the 'passwordChange' permission for the above user(%%) ===
298 298  
299 299  {{code language="bash"}}
300 - 
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
301 301  {{/code}}
302 302  
303 -=== Delete ===
336 +=== Remove the 'passwordChange' permission for the above user ===
304 304  
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 +
305 305  {{code language="bash"}}
306 - 
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
307 307  {{/code}}
308 308  {{/layout-cell}}
309 309  {{/layout-section}}