Skip to Content

Wiki source code of Permissions Configuration

Version 11.1 by colinw on 2014/11/10 23:01
Show last authors
1 {{warning}}
2 This page is currently being written. Although the information below is probably accurate, it may not be complete or may have errors.
3 {{/warning}}
4
5
6
7 ==== **//On this page~://** ====
8
9
10
11 {{toc maxLevel="2" indent="1"/}}
12
13 = Description =
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
17 === Overview ===
18
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 === Defaults ===
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.
24
25 === **Exceptions** ===
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.
28
29 = Root Resource Paths =
30
31 {{code}}
32 communication_manager/api/resource/core/{core_server_id}/permissions
33 communication_manager/api/resource/core/getBySlug/{core_server_slug}/permissions
34 {{/code}}
35
36 = JSON Representation =
37
38 {{code title="PermissionConfig" language="js"}}
39 {
40 "key": "cellPhoneOriginateTo",
41 "allowed": false,
42 "exceptions": [
43 "df41edec-2707-46eb-8b8f-146b01d9b29e"
44 ],
45 "inherited": false
46 }
47 {{/code}}
48
49 |=(((
50 Property
51 )))|=(((
52 Type
53 )))|=(((
54 Description
55 )))
56 |(((
57 {{{key}}}
58 )))|(((
59 String
60 )))|(((
61 The key used for this permission configuration.
62 )))
63 |(% colspan="1" %)(% colspan="1" %)
64 (((
65 allowed
66 )))|(% colspan="1" %)(% colspan="1" %)
67 (((
68 Boolean
69 )))|(% colspan="1" %)(% colspan="1" %)
70 (((
71 Whether the action should be generally allowed or not.
72 )))
73 |(% colspan="1" %)(% colspan="1" %)
74 (((
75 exceptions
76 )))|(% colspan="1" %)(% colspan="1" %)
77 (((
78 Array of Strings (UUID)
79 )))|(% colspan="1" %)(% colspan="1" %)
80 (((
81 The objects defined in the exceptions will be granted or denied access as exceptions to the general rule.
82 )))
83 |(% colspan="1" %)(% colspan="1" %)
84 (((
85 inherited
86 )))|(% colspan="1" %)(% colspan="1" %)
87 (((
88 Boolean
89 )))|(% colspan="1" %)(% colspan="1" %)
90 (((
91 Used internally. Should never be true when using the REST system.
92 )))
93
94 = Resource Paths =
95
96 |=(% colspan="2" %)(% colspan="2" %)
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}}}}
101 )))
102 |(% class="highlight-grey" data-highlight-colour="grey" %)(% class="highlight-grey" data-highlight-colour="grey" %)
103 (((
104 **Description**
105 )))|(((
106 Retrieves permissions for the user group identified by the {user_group_id} path parameter.
107
108 **Parameters**:
109
110 * core_server_id: The UUID of the core server.
111 * core_server_slug: The unique identifying slug of the core server.
112 * user_group_id: The UUID of the user group.
113
114 **Errors**:
115
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 )))
118 |(% class="highlight-grey" data-highlight-colour="grey" %)(% class="highlight-grey" data-highlight-colour="grey" %)
119 (((
120 **GET**
121 )))|(((
122 Retrieves all permissions defined for the user group.
123 )))
124
125 |=(% colspan="2" %)(% colspan="2" %)
126 (((
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 )))
131 |(% class="highlight-grey" data-highlight-colour="grey" %)(% class="highlight-grey" data-highlight-colour="grey" %)
132 (((
133 **Description**
134 )))|(((
135 Retrieves or updates a specific permission for a user group.
136
137 **Parameters**:
138
139 * core_server_id: The UUID of the core server.
140
141 * core_server_slug: The unique identifying slug of the core server.
142
143 * user_group_id: The UUID of the user group.
144
145 * key: The permission key identifying the permission.
146
147 **Errors**:
148
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 )))
151 |(% class="highlight-grey" data-highlight-colour="grey" %)(% class="highlight-grey" data-highlight-colour="grey" %)
152 (((
153 **GET**
154 )))|(((
155 Retrieves a specific permission for the user group.
156
157 **Errors**:
158
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 )))
161 |(% class="highlight-grey" data-highlight-colour="grey" %)(% class="highlight-grey" data-highlight-colour="grey" %)
162 (((
163 **PUT**
164 )))|(((
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
167 **Errors**:
168
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 * 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 )))
172 |(% class="highlight-grey" colspan="1" data-highlight-colour="grey" %)(% class="highlight-grey" colspan="1" data-highlight-colour="grey" %)
173 (((
174 **DELETE**
175 )))|(% colspan="1" %)(% colspan="1" %)
176 (((
177 Clears the specific permission definition for the user group.
178
179 **Errors**:
180
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 )))
183
184 |=(% colspan="2" %)(% colspan="2" %)
185 (((
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 )))
190 |(% class="highlight-grey" data-highlight-colour="grey" %)(% class="highlight-grey" data-highlight-colour="grey" %)
191 (((
192 **Description**
193 )))|(((
194 Retrieves permissions for the user group identified by the {user_id} path parameter.
195
196 **Parameters**:
197
198 * core_server_id: The UUID of the core server.
199 * core_server_slug: The unique identifying slug of the core server.
200 * user_id: The UUID of the user.
201
202 **Errors**:
203
204 * 404 'No user exists with that id.': Returned if the provided user_id does not match a user in the system.
205 )))
206 |(% class="highlight-grey" data-highlight-colour="grey" %)(% class="highlight-grey" data-highlight-colour="grey" %)
207 (((
208 **GET**
209 )))|(((
210 Retrieves all permissions defined for the user.
211 )))
212
213 |=(% colspan="2" %)(% colspan="2" %)
214 (((
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 )))
219 |(% class="highlight-grey" data-highlight-colour="grey" %)(% class="highlight-grey" data-highlight-colour="grey" %)
220 (((
221 **Description**
222 )))|(((
223 Retrieves or updates a specific permission for a user group.
224
225 **Parameters**:
226
227 * core_server_id: The UUID of the core server.
228
229 * core_server_slug: The unique identifying slug of the core server.
230
231 * user_id: The UUID of the user.
232
233 * key: The permission key identifying the permission.
234
235 **Errors**:
236
237 * 404 'No user exists with that id.': Returned if the provided user_id does not match a user in the system.
238 )))
239 |(% class="highlight-grey" data-highlight-colour="grey" %)(% class="highlight-grey" data-highlight-colour="grey" %)
240 (((
241 **GET**
242 )))|(((
243 Retrieves a specific permission for the user.
244
245 **Errors**:
246
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 )))
249 |(% class="highlight-grey" data-highlight-colour="grey" %)(% class="highlight-grey" data-highlight-colour="grey" %)
250 (((
251 **PUT**
252 )))|(((
253 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.
254
255 **Errors**:
256
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 * 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 )))
260 |(% class="highlight-grey" colspan="1" data-highlight-colour="grey" %)(% class="highlight-grey" colspan="1" data-highlight-colour="grey" %)
261 (((
262 **DELETE**
263 )))|(% colspan="1" %)(% colspan="1" %)
264 (((
265 Clears the specific permission definition for the user.
266
267 **Errors**:
268
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 )))
271
272 = Curl Examples =
273
274 === Get ===
275
276 {{code language="bash"}}
277  
278 {{/code}}
279
280 === (% style="color: rgb(0,0,0);" %)Update(%%) ===
281
282 {{code language="bash"}}
283  
284 {{/code}}
285
286 === Add ===
287
288 {{code language="bash"}}
289  
290 {{/code}}
291
292 === Delete ===
293
294 {{code language="bash"}}
295  
296 {{/code}}