cubicweb: comparison doc/book/en/devrepo/datamodel/definition.rst

equal deleted inserted replaced

-:528be1e059aa
+:59c446a813b5
 * permissions are assigned to groups (and not to users)
 For *CubicWeb* in particular:
 * we associate rights at the entities/relations schema level
-* for each entity, we distinguish four kinds of permissions: `read`,
-`add`, `update` and `delete`
-* for each relation, we distinguish three kinds of permissions: `read`,
-`add` and `delete` (it is not possible to `modify` a relation)
 * the default groups are: `administrators`, `users` and `guests`
-* by default, users belong to the `users` group
-* there is a virtual group called `owners` to which we
+* users belong to the `users` group
-can associate only `delete` and `update` permissions
+* there is a virtual group called `owners` to which we can associate only
-* we can not add users to the `Owners` group, they are
+`delete` and `update` permissions
-implicitly added to it according to the context of the objects
-they own
+* we can not add users to the `owners` group, they are implicitly added to it
-* the permissions of this group are only checked on `update`/`delete`
+according to the context of the objects they own
-actions if all the other groups the user belongs to do not provide
-those permissions
+* the permissions of this group are only checked on `update`/`delete` actions
+if all the other groups the user belongs to do not provide those permissions
 Setting permissions is done with the attribute `__permissions__` of entities and
-relation types. The value of this attribute is a dictionary where the keys are the access types
+relation definition. The value of this attribute is a dictionary where the keys
-(action), and the values are the authorized groups or expressions.
+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 a relation, the possible actions are `read`, `add`, and `delete`.
+For an attribute, the possible actions are `read`, and `update`.
 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 if the user is in one of the listed groups or if one of the RQL condition
 is satisfied.
 The standard user groups
 ````````````````````````
 * `guests`
 * `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
+It is also possible to use specific groups if they are defined in the precreate
-precreate script of the cube (``migration/precreate.py``). Defining groups in
+script of the cube (``migration/precreate.py``). Defining groups in postcreate
-postcreate script or later makes them unavailable for security
+script or later makes them unavailable for security purposes (in this case, an
-purposes (in this case, an `sync_schema_props_perms` command has to
+`sync_schema_props_perms` command has to be issued in a CubicWeb shell).
-be issued in a CubicWeb shell).
 Use of RQL expression for write permissions
 ```````````````````````````````````````````
-It is possible to define RQL expression to provide update permission
-(`add`, `delete` and `update`) on relation and entity types.
+It is possible to define RQL expression to provide update permission (`add`,
+`delete` and `update`) on entity type / relation definitions. An rql expression
-RQL expression for entity type permission:
+is a piece of query (corresponds to the WHERE statement of an RQL query), and the
+expression will be considered as satisfied if it returns some results. They can
-* you have to use the class `ERQLExpression`
+not be used in `read` permission.
-* the used expression corresponds to the WHERE statement of an RQL query
+To use RQL expression in entity type permission:
+* you have to use the class :class:`~cubicweb.schema.ERQLExpression`
 * in this expression, the variables `X` and `U` are pre-defined references
-respectively on the current entity (on which the action is verified) and
+respectively on the current entity (on which the action is verified) and on the
-on the user who send the request
+user who send the request
-* it is possible to use, in this expression, a special relation
+For RQL expressions on a relation type, the principles are the same except for
-"has_<ACTION>_permission" where the subject is the user and the
+the following:
-object is any variable, meaning that the user needs to have
-permission to execute the action <ACTION> on the entities related
+* you have to use the class :class:`~cubicweb.schema.RRQLExpression` instead of
-to this variable
+:class:`~cubicweb.schema.ERQLExpression`
-For RQL expressions on a relation type, the principles are the same except
+* in the expression, the variables `S`, `O` and `U` are pre-defined references to
-for the following:
+respectively the subject and the object of the current relation (on which the
+action is being verified) and the user who executed the query
-* you have to use the class `RRQLExpression` in the case of a non-final relation
+To define security for attributes of an entity (non-final relation), you have to
-* in the expression, the variables `S`, `O` and `U` are pre-defined references
+use the class :class:`~cubicweb.schema.ERQLExpression` in which `X` represents
-to respectively the subject and the object of the current relation (on
+the entity the attribute belongs to.
-which the action is being verified) and the user who executed the query
+It is possible to use in those expression a special relation
-* we can also define rights over attributes of an entity (non-final relation),
+`has_<ACTION>_permission` where the subject is the user (eg 'U') and the object
-knowing that:
+is any variable representing an entity (usually 'X' in
+:class:`~cubicweb.schema.ERQLExpression`, 'S' or 'O' in
-- to define RQL expression, we have to use the class `ERQLExpression`
+:class:`~cubicweb.schema.RRQLExpression`), meaning that the user needs to have
-in which `X` represents the entity the attribute belongs to
+permission to execute the action <ACTION> on the entities represented by this
+variable. It's recommanded to use this feature whenever possible since it
-- the permissions `add` and `delete` are equivalent. Only `add`/`read`
+simplify greatly complex security definition and upgrade.
-are actually taken in consideration.
+.. sourcecode:: python
+class my_relation(RelationDefinition):
+__permissions__ = {'read': ('managers', 'users'),
+'add': ('managers', RRQLExpression('U has_update_permission S')),
+'delete': ('managers', RRQLExpression('U has_update_permission S'))
+		       }
+In the above example, user will be allowed to add/delete `my_relation` if he has
+the `update` permission on the subject of the relation.
 .. note::
-Potentially, the `use of an RQL expression to add an entity or a
+Potentially, the `use of an RQL expression to add an entity or a relation` can
-relation` can cause problems for the user interface, because if the
+cause problems for the user interface, because if the expression uses the
-expression uses the entity or the relation to create, then we are
+entity or the relation to create, we are not able to verify the permissions
-not able to verify the permissions before we actually add the entity
+before we actually added the entity (please note that this is not a problem for
-(please note that this is not a problem for the RQL server at all,
+the RQL server at all, because the permissions checks are done after the
-because the permissions checks are done after the creation). In such
+creation). In such case, the permission check methods
-case, the permission check methods (CubicWebEntitySchema.check_perm
+(CubicWebEntitySchema.check_perm and has_perm) can indicate that the user is
-and has_perm) can indicate that the user is not allowed to create
+not allowed to create this entity while it would obtain the permission.  To
-this entity but can obtain the permission.  To compensate this
+compensate this problem, it is usually necessary in such case to use an action
-problem, it is usually necessary, for such case, to use an action
+that reflects the schema permissions but which check properly the permissions
-that reflects the schema permissions but which enables to check
+so that it would show up only if possible.
-properly the permissions so that it would show up if necessary.
 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
+* you can not use rql expression for the `read` permission of relations and
+attributes,
-* special relations "has_<ACTION>_permission" can not be used
+* you can not use special `has_<ACTION>_permission` relation in the rql
+expression.
 Important notes about write permissions checking
 ````````````````````````````````````````````````

branch	stable
changeset 6148	59c446a813b5
parent 6120	c000e41316ec
child 6150	98642a11aea3