Skip to Content

Wiki source code of Permissions Configuration

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