+
−.. -*- coding: utf-8 -*-
+
−
+
−The security model
+
−------------------
+
−
+
−The security model of `cubicWeb` is based on `Access Control List`. 
+
−The main principles are:
+
−
+
−* users and groups of users
+
−* a user belongs to at least one group of user
+
−* permissions (read, update, create, delete)
+
−* permissions are assigned to groups (and not to users)
+
−
+
−For *CubicWeb* in particular:
+
−
+
−* we associate rights at the enttities/relations schema level
+
−* for each entity, we distinguish four kind of permissions: read,
+
−  add, update and delete
+
−* for each relation, we distinguish three king of permissions: read,
+
−  add and delete (we can not modify a relation)
+
−* the basic groups are: Administrators, Users and Guests
+
−* by default, users belongs to the group Users
+
−* there is a virtual group called `Owners users` to which we
+
−  can associate only deletion and update permissions
+
−* we can not add users to the `Owners users` group, they are
+
−  implicetely added to it according to the context of the objects
+
−  they own
+
−* the permissions of this group are only be checked on update/deletion
+
−  actions if all the other groups the user belongs does not provide
+
−  those permissions
+
−
+
−  
+
−Permissions definition
+
−``````````````````````
+
−
+
−Setting permissions is done with the attribute `permissions` of entities and
+
−relation types. It defines a dictionary where the keys are the access types
+
−(action), and the values are the authorized groups or expressions.
+
−
+
−For an entity type, the possible actions are `read`, `add`, `update` and
+
−`delete`.
+
−
+
−For a relation type, the possible actions are `read`, `add`, and `delete`.
+
−
+
−For each access type, a tuple indicates the name of the authorized groups and/or
+
−one or multiple RQL expressions to satisfy to grant access. The access is
+
−provided once the user is in the listed groups or one of the RQL condition is
+
−satisfied.
+
−
+
−The standard groups are :
+
−
+
−* `guests`
+
−
+
−* `users`
+
−
+
−* `managers`
+
−
+
−* `owners` : virtual group corresponding to the entity's owner.
+
−  This can only be used for the actions `update` and `delete` of an entity
+
−  type.
+
−
+
−It is also possible to use specific groups if they are defined in the precreate 
+
−of the cube (``migration/precreate.py``).
+
−
+
−
+
−Use of RQL expression for writing rights
+
−````````````````````````````````````````
+
−
+
−It is possible to define RQL expression to provide update permission 
+
−(`add`, `delete` and `update`) on relation and entity types.
+
−
+
−RQL expression for entity type permission :
+
−
+
−* you have to use the class `ERQLExpression`
+
−
+
−* the used expression corresponds to the WHERE statement of an RQL query
+
−
+
−* in this expression, the variables X and U are pre-defined references
+
−  respectively on the current entity (on which the action is verified) and
+
−  on the user who send the request
+
−
+
−* it is possible to use, in this expression, a special relation 
+
−  "has_<ACTION>_permission" where the subject is the user and the 
+
−  object is a any variable, meaning that the user needs to have
+
−  permission to execute the action <ACTION> on the entities related
+
−  to this variable 
+
−
+
−For RQL expressions on a relation type, the principles are the same except 
+
−for the following :
+
−
+
−* you have to use the class `RQLExpression` in the case of a non-final relation
+
−
+
−* in the expression, the variables S, O and U are pre-defined references
+
−  to respectively the subject and the object of the current relation (on
+
−  which the action is being verified) and the user who executed the query
+
−
+
−* we can also defined rights on attributes of an entity (non-final relation),
+
−  knowing that : 
+
−
+
−  - to defines RQL expression, we have to use the class `ERQLExpression`
+
−    in which X represents the entity the attribute belongs to
+
−
+
−  - the permissions `add` and `delete` are equivalent. Only `add`/`read`
+
−    are actually taken in consideration.
+
−
+
−In addition to that the entity type `EPermission` from the standard library
+
−allow to build very complex and dynamic security architecture. The schema of
+
−this entity type is as follow : ::
+
−
+
−    class EPermission(MetaEntityType):
+
−	"""entity type that may be used to construct some advanced security configuration
+
−	"""
+
−	name = String(required=True, indexed=True, internationalizable=True, maxsize=100)
+
−	require_group = SubjectRelation('EGroup', cardinality='+*',
+
−					description=_('groups to which the permission is granted'))
+
−	require_state = SubjectRelation('State',
+
−				    description=_("entity'state in which the permission is applyable"))
+
−	# can be used on any entity
+
−	require_permission = ObjectRelation('**', cardinality='*1', composite='subject',
+
−					    description=_("link a permission to the entity. This "
+
−							  "permission should be used in the security "
+
−							  "definition of the entity's type to be useful."))
+
−
+
−
+
−Example of configuration ::
+
−
+
−
+
−    ...
+
−
+
−    class Version(EntityType):
+
−	"""a version is defining the content of a particular project's release"""
+
−
+
−	permissions = {'read':   ('managers', 'users', 'guests',),
+
−		       'update': ('managers', 'logilab', 'owners',),
+
−		       'delete': ('managers', ),
+
−		       'add':    ('managers', 'logilab',
+
−				  ERQLExpression('X version_of PROJ, U in_group G,'
+
−						 'PROJ require_permission P, P name "add_version",'
+
−						 'P require_group G'),)}
+
−
+
−    ...
+
−
+
−    class version_of(RelationType):
+
−	"""link a version to its project. A version is necessarily linked to one and only one project.
+
−	"""
+
−	permissions = {'read':   ('managers', 'users', 'guests',),
+
−		       'delete': ('managers', ),
+
−		       'add':    ('managers', 'logilab',
+
−				  RRQLExpression('O require_permission P, P name "add_version",'
+
−						 'U in_group G, P require_group G'),)
+
−		       }
+
−	inlined = True
+
−
+
−This configuration indicates that an entity `EPermission` named
+
−"add_version" can be associated to a project and provides rights to create
+
−new versions on this project to specific groups. It is important to notice that :
+
−
+
−* in such case, we have to protect both the entity type "Version" and the relation
+
−  associating a version to a project ("version_of")
+
−
+
−* because of the genricity of the entity type `EPermission`, we have to execute
+
−  a unification with the groups and/or the states if necessary in the expression
+
−  ("U in_group G, P require_group G" in the above example)
+
−
+
−Use of RQL expression for reading rights
+
−````````````````````````````````````````
+
−
+
−The principles are the same but with the following restrictions :
+
−
+
−* we can not use `RRQLExpression` on relation types for reading
+
−
+
−* special relations "has_<ACTION>_permission" can not be used
+
−
+
−
+
−Note on the use of RQL expression for `add` permission
+
−``````````````````````````````````````````````````````
+
−Potentially, the use of an RQL expression to add an entity or a relation
+
−can cause problems for the user interface, because if the expression uses
+
−the entity or the relation to create, then we are not able to verify the 
+
−permissions before we actually add the entity (please note that this is
+
−not a problem for the RQL server at all, because the permissions checks are
+
−done after the creation). In such case, the permission check methods 
+
−(check_perm, has_perm) can indicate that the user is not allowed to create 
+
−this entity but can obtain the permission. 
+
−To compensate this problem, it is usually necessary, for such case,
+
−to use an action that reflects the schema permissions but which enables
+
−to check properly the permissions so that it would show up if necessary.
+
−