Permission objects
The permission system is based on permission objects in the db which are checked before executing a request. Which permission is needed for what action is hardcoded and can be found in the api documentation where it is described for every request. A permission has the following properties:
| field | desc |
|---|---|
| scope | Where that permission is applied. Can be global (whole system) or local. Local means it is only applied inside the body the user got it from plus all bound circles in that body plus all members of that body. |
| action | Which action, e.g. update, view, etc |
| object | Which object, e.g. circle, body, etc |
| filters | Field filters in the form of nested objects with a field parameter {field: "something"}. See separate section for filters |
| always_assigned | Boolean whether the permission is auto-assigned to everyone in the system |
| description | Description |
For easier communication we write a permission as scope:action:object or if scope doesn't matter as action:object
Permission inheritance
Generally permissions can only be aquired through circle membership, except always_assigned permissions and superadmins. If a member is member in a circle, all permissions which are attached to that circle directly or to any of the parent circles will be granted to the member. Locally scoped permissions can only be aquired through a bound circle, if you are in a free circle which assigns you a local permission you will not be granted that permission. Still, even local permissions are inherited, so local permissions on a free circle can be aquired by joining a bound child circle.
Field filters
If a filtered permission was granted, that excludes the set field from the permission. E.g. If a user has a view:circle permission with "name" filtered, he will be able to see everything of all circles except for the name. For knowing how the fields are called, see the JSON responses in the API documentation. If a user has two permissions for the same action:object, he will have access to all fields that are not filtered in both permissions, i.e. on two permissions filters are determined by set intersection. It is furthermore possible to set nested filters if a request delivers nested results. Let's take the request for a single body which has circles preloaded. If you don't want the user to see the name of the circle in that result, you could assign him the view:body permission with a filter of "circles.name". If you filter out "id" or "seo_url" you might break the frontend. Currently filtered permissions are supported for update and view request, in the API documentation it is mentioned alongside each request if it supports filtered permissions.
Wise words
When giving out permissions, try to be as conservative as possible and assign only what really needs to be assigned. Also assign it to circles which are as protected as possible. If only members of the CD need a certain permission, don't assign it through a free circle as on the bound circle, only members of the body could join.
Don't delete the create:permission permission. Not even the superadmin will have it anymore then and it would require a hard reset of the system or some iex-hacking.
List of permissions
To see a list of permissions, visit https://oms.aegee.org/permissions, It is thinkable that new microservices can add a new set of permissions to the system to handle specific functions.
Permission contexts
There are different objects in the system that get permission differently, in total there are 4. They can be checked through the /my_permissions request on each of the objects.
- Global for general requests only the global permissions are regarded. For this the user gets assigned all auto-assigned permissions and all global permissions that he received through any circle membership. All other permission contexts take this as a basis
- Body for body-related requests additionally all local permissions that are aquired through membership in a bound circle of that very body are added to the permission list.
- Circle in case it is a bound circle, all body permissions the body that the circle is bound to are added. For free circles, nothing is added. Circle-admin status however brings some additional permissions.
- Member member-based request additionally get all body permissions of all bodies the member is part of. So only in case the requesting member and the requested member have bodies in common, permissions will be added. If you are requesting yourself, you get full permissions.
Future permission system improvements
- Extending scoping options. Instead of just local and global we could also use a body type of a local as scope.