Permissions
Multiple parameters are put together to determine the permissions that were granted for each user:
- Request Type (scoped/unscoped)
- Model and objects definition
- Scopes of user
- User Level
These criteria are ordered by strength (from the strongest criterion to the weakest).
Request Type
When performing a request to the API Concrete (get, post, patch, delete), the scope (X-ENTITY-UID
) can be added to the headers of the request:
The scope passed in the headers of a request is used to filter the response's objects, and allows access only to the objects having the same scope.
Unscoped Request
curl \
-X GET \
-H "Authorization: Token b1cccee29710b53386b964d93847648a526005a8" \
"https://<webapp>/api/v1.1/<model-name>/"
Scoped Request
curl \
-X GET \
-H "Authorization: Token b1cccee29710b53386b964d93847648a526005a8" \
-H "X-ENTITY-UID: 7508ffd7-2d10-413e-86b6-4adab3767413" \
"https://<webapp>/api/v1.1/<model-name>/"
Example: given two scopes scopeA
and scopeB
and a model MyModel
accessible through a url
. Given objects:
object1: scope=scopeA
object2: scope=scopeB
object3: scope=None
object4: scope=scopeA
A SuperUser with a token super_token
makes the request to get a list of the objects of the model MyModel
.
-
Unscoped Request:
requests.get(url,headers={"Authorization":"Token {}".format(super_token)})
returns a list of objects within a JSON response, containing all of the four objects. -
Scoped Request:
requests.get(url,headers={"Authorization":"Token {}".format(super_token),"X-ENTITY-UID":scopeA.uid})
returns a list containing only the objects with the scopescopeA
(i.e onlyobject1
andobject4
).
Model and Object Definition
Model Definition
For a model, some user level constraints are set to determine whether a given user can perform a given operation (create, delete, retrieve and update) or not:
{
"ext.m_creation_minimum_level": "admin",
"ext.m_delete_minimum_level": "superuser",
"ext.m_retrieve_minimum_level": "authenticated",
"ext.m_update_minimum_level": "manager"
}
Object Definition
Objects can have arguments that allow a user (or a group of users) to perform some operations that he can't normally perform:
can_view_users
,can_view_groups
: givesRetrieve
rights to a user or a group of users.can_admin_users
,can_admin_groups
: givesRetrieve
andUpdate
rights to a user or a group of users.public
: a boolean. If set to false, a user with levelmanager
or less can't have access to this object unless he is the owner (created_by
) or listed incan_admin_[users/groups]
orcan_view_[users/groups]
.
User levels
There are five user levels with a set of permissions and privileges:
Superuser > Admin > Manager > Simpleuser > Blocked
- The
superuser
has access to everything and has all the rights. - The other levels have different create and retrieve permissions, depending on the model and the created instance.
- The
blocked
user has access to nothing.
User Scopes
A user can have one or more scopes that are used to determine the range of objects accessible to him.
A user of an admin
level or higher has access to all the objects, independently of his scopes.
For a level manager
or less, if the user has a scope A
, he can access to all the objects having a scope A
(and only these objects).
The possible operations on these objects are those that satisfy the model's definition.
Example
Given two scopes: Divider_X
and Divider_Y
Given the following users:
- SuperUser: without scopes.
- Admin: without scopes.
- Manager: without scopes.
- Manager_X: with scope
Divider_X
. - Manager_Y: with scope
Divider_Y
. - Manager_XY: with scopes
Divider_X
andDivider_Y
. - SimpleUser: without scopes.
- SimpleUser_X: with scope
Divider_X
. - SimpleUser_Y: with scope
Divider_Y
. - SimpleUser_XY: with scopes
Divider_X
andDivider_Y
.
Given a Divided Model MyModel
and four instances of this model with the following configuration:
1st case: For A Scoped Request With The Scope Divider_X:
- SuperUser: can access to
instance_1
andinstance_3
and has all the rights. - Admin: can access to
instance_1
andinstance_3
and has retrieve, create and update rights - Manager: can access to
instance_3
(because ofcan_view_users
) with retrieve rights andinstance_1
(because ofcan_admin_users
) with retrieve and update rights - Manager_X: can access to
instance_1
andinstance_3
(because of scope) and has retrieve and update rights - Manager_Y: has access only to
instance_3
(because ofcan_admin_users
) and has retrieve and update rights. - Manager_XY: can access to
instance_1
andinstance_3
and has retrieve and update rights - SimpleUser: has access only to
instance_1
(because ofcan_view_users
) and has only retrieve rights - SimpleUser_X: has access to
instance_1
andinstance_3
(because of scope) and has only retrieve rights - SimpleUser_Y: has access to nothing
- SimpleUser_XY: has access to
instance_1
andinstance_3
(because of scope) and has only retrieve rights
2nd case: For A Scoped Request With The Scope Divider_Y:
- SuperUser: can access to
instance_2
and has all the rights. - Admin: can access to
instance_2
and has retrieve, create and update rights - Manager: has access to nothing
- Manager_X: can access to
instance_2
(because ofcan_view_users
) and has only retrieve rights - Manager_Y: has access to
instance_2
(because of scope) and has retrieve and update rights. - Manager_XY: can access to
instance_2
and has retrieve and update rights - SimpleUser: has access
instance_2
(because ofcan_admin_users
) and has only retrieve rights - SimpleUser_X: has access to nothing
- SimpleUser_Y: has access to
instance_2
with retrieve rights - SimpleUser_XY: has access to
instance_2
(because of scope) and has only retrieve rights
3rd case: For A Non-Scoped Request:
- SuperUser: can access to everything and has all the rights.
- Admin: can access to everything and has retrieve, create and update rights
- Manager: can access to
instance_3
(because ofcan_view_users
) with retrieve rights andinstance_1
(because ofcan_admin_users
) with retrieve and update rights - Manager_X: can access to
instance_2
(because ofcan_view_users
) with only retrieve rights, and can access toinstance_1
andinstance_3
(because of scope) with retrieve and update rights - Manager_Y: has access to
instance_2
(because of scope) and toinstance_3
(because ofcan_admin_users
) and has retrieve and update rights. - Manager_XY: can access to everything and has retrieve and update rights
- SimpleUser: has access
instance_2
(because ofcan_admin_users
) andinstance_1
(because ofcan_view_users
) and has only retrieve rights - SimpleUser_X: has access to
instance_1
andinstance_3
(because of scope) as well asinstance_4
(because of public) and has only retrieve rights - SimpleUser_Y: has access to
instance_2
(because of scope) andinstance_4
(because of public) with retrieve rights - SimpleUser_XY: has access to everything (because of scopes and public) and has only retrieve rights