--- a/doc/book/en/B0015-define-permissions.en.txt Fri Oct 02 15:31:28 2009 +0200
+++ b/doc/book/en/B0015-define-permissions.en.txt Mon Oct 05 16:04:14 2009 +0200
@@ -3,7 +3,7 @@
The security model
------------------
-The security model of `cubicWeb` is based on `Access Control List`.
+The security model of `cubicWeb` is based on `Access Control List`.
The main principles are:
* users and groups of users
@@ -29,7 +29,7 @@
actions if all the other groups the user belongs does not provide
those permissions
-
+
Permissions definition
``````````````````````
@@ -59,14 +59,14 @@
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
+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
+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 :
@@ -79,47 +79,66 @@
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
+* 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
+ to this variable
-For RQL expressions on a relation type, the principles are the same except
+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
+* you have to use the class `RRQLExpression` 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 :
+* we can also define 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
+ - to define 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
+allows to build very complex and dynamic security architecture. The schema of
this entity type is as follow : ::
- class EPermission(MetaEntityType):
+ class CWPermission(EntityType):
"""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 applicable"))
- # 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."))
+ permissions = META_ETYPE_PERMS
+
+ name = String(required=True, indexed=True, internationalizable=True, maxsize=100,
+ description=_('name or identifier of the permission'))
+ label = String(required=True, internationalizable=True, maxsize=100,
+ description=_('distinct label to distinguate between other permission entity of the same name'))
+ require_group = SubjectRelation('CWGroup',
+ description=_('groups to which the permission is granted'))
+
+ # explicitly add X require_permission CWPermission for each entity that should have
+ # configurable security
+ class require_permission(RelationType):
+ """link a permission to the entity. This permission should be used in the
+ security definition of the entity's type to be useful.
+ """
+ permissions = {
+ 'read': ('managers', 'users', 'guests'),
+ 'add': ('managers',),
+ 'delete': ('managers',),
+ }
+
+ class require_group(RelationType):
+ """used to grant a permission to a group"""
+ permissions = {
+ 'read': ('managers', 'users', 'guests'),
+ 'add': ('managers',),
+ 'delete': ('managers',),
+ }
Example of configuration ::
@@ -151,14 +170,14 @@
}
inlined = True
-This configuration indicates that an entity `EPermission` named
+This configuration indicates that an entity `CWPermission` 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
+* because of the genericity of the entity type `CWPermission`, 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)
@@ -176,12 +195,13 @@
``````````````````````````````````````````````````````
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
+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.
+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.