doc/book/en/B0015-define-permissions.en.txt
author Nicolas Chauvat <nicolas.chauvat@logilab.fr>
Wed, 15 Apr 2009 18:16:12 +0200
changeset 1585 b86448eaed66
child 2175 16d3c37c5d28
permissions -rw-r--r--
[doc] reduce the depth of the table of contents to get latex generation working
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
1585
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
     1
.. -*- coding: utf-8 -*-
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
     2
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
     3
The security model
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
     4
------------------
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
     5
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
     6
The security model of `cubicWeb` is based on `Access Control List`. 
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
     7
The main principles are:
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
     8
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
     9
* users and groups of users
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    10
* a user belongs to at least one group of user
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    11
* permissions (read, update, create, delete)
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    12
* permissions are assigned to groups (and not to users)
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    13
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    14
For `CubicWeb` in particular:
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    15
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    16
* we associate rights at the enttities/relations schema level
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    17
* for each entity, we distinguish four kind of permissions: read,
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    18
  add, update and delete
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    19
* for each relation, we distinguish three king of permissions: read,
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    20
  add and delete (we can not modify a relation)
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    21
* the basic groups are: Administrators, Users and Guests
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    22
* by default, users belongs to the group Users
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    23
* there is a virtual group called `Owners users` to which we
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    24
  can associate only deletion and update permissions
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    25
* we can not add users to the `Owners users` group, they are
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    26
  implicetely added to it according to the context of the objects
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    27
  they own
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    28
* the permissions of this group are only be checked on update/deletion
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    29
  actions if all the other groups the user belongs does not provide
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    30
  those permissions
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    31
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    32
  
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    33
Permissions definition
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    34
``````````````````````
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    35
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    36
Setting permissions is done with the attribute `permissions` of entities and
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    37
relation types. It defines a dictionary where the keys are the access types
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    38
(action), and the values are the authorized groups or expressions.
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    39
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    40
For an entity type, the possible actions are `read`, `add`, `update` and
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    41
`delete`.
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    42
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    43
For a relation type, the possible actions are `read`, `add`, and `delete`.
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    44
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    45
For each access type, a tuple indicates the name of the authorized groups and/or
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    46
one or multiple RQL expressions to satisfy to grant access. The access is
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    47
provided once the user is in the listed groups or one of the RQL condition is
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    48
satisfied.
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    49
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    50
The standard groups are :
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    51
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    52
* `guests`
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    53
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    54
* `users`
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    55
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    56
* `managers`
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    57
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    58
* `owners` : virtual group corresponding to the entity's owner.
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    59
  This can only be used for the actions `update` and `delete` of an entity
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    60
  type.
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    61
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    62
It is also possible to use specific groups if they are defined in the precreate 
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    63
of the cube (``migration/precreate.py``).
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    64
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    65
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    66
Use of RQL expression for writing rights
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    67
````````````````````````````````````````
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    68
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    69
It is possible to define RQL expression to provide update permission 
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    70
(`add`, `delete` and `update`) on relation and entity types.
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    71
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    72
RQL expression for entity type permission :
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    73
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    74
* you have to use the class `ERQLExpression`
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    75
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    76
* the used expression corresponds to the WHERE statement of an RQL query
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    77
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    78
* in this expression, the variables X and U are pre-defined references
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    79
  respectively on the current entity (on which the action is verified) and
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    80
  on the user who send the request
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    81
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    82
* it is possible to use, in this expression, a special relation 
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    83
  "has_<ACTION>_permission" where the subject is the user and the 
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    84
  object is a any variable, meaning that the user needs to have
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    85
  permission to execute the action <ACTION> on the entities related
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    86
  to this variable 
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    87
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    88
For RQL expressions on a relation type, the principles are the same except 
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    89
for the following :
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    90
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    91
* you have to use the class `RQLExpression` in the case of a non-final relation
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    92
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    93
* in the expression, the variables S, O and U are pre-defined references
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    94
  to respectively the subject and the object of the current relation (on
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    95
  which the action is being verified) and the user who executed the query
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    96
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    97
* we can also defined rights on attributes of an entity (non-final relation),
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    98
  knowing that : 
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    99
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   100
  - to defines RQL expression, we have to use the class `ERQLExpression`
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   101
    in which X represents the entity the attribute belongs to
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   102
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   103
  - the permissions `add` and `delete` are equivalent. Only `add`/`read`
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   104
    are actually taken in consideration.
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   105
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   106
In addition to that the entity type `EPermission` from the standard library
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   107
allow to build very complex and dynamic security architecture. The schema of
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   108
this entity type is as follow : ::
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   109
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   110
    class EPermission(MetaEntityType):
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   111
	"""entity type that may be used to construct some advanced security configuration
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   112
	"""
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   113
	name = String(required=True, indexed=True, internationalizable=True, maxsize=100)
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   114
	require_group = SubjectRelation('EGroup', cardinality='+*',
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   115
					description=_('groups to which the permission is granted'))
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   116
	require_state = SubjectRelation('State',
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   117
				    description=_("entity'state in which the permission is applyable"))
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   118
	# can be used on any entity
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   119
	require_permission = ObjectRelation('**', cardinality='*1', composite='subject',
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   120
					    description=_("link a permission to the entity. This "
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   121
							  "permission should be used in the security "
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   122
							  "definition of the entity's type to be useful."))
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   123
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   124
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   125
Example of configuration ::
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   126
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   127
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   128
    ...
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   129
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   130
    class Version(EntityType):
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   131
	"""a version is defining the content of a particular project's release"""
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   132
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   133
	permissions = {'read':   ('managers', 'users', 'guests',),
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   134
		       'update': ('managers', 'logilab', 'owners',),
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   135
		       'delete': ('managers', ),
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   136
		       'add':    ('managers', 'logilab',
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   137
				  ERQLExpression('X version_of PROJ, U in_group G,'
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   138
						 'PROJ require_permission P, P name "add_version",'
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   139
						 'P require_group G'),)}
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   140
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   141
    ...
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   142
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   143
    class version_of(RelationType):
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   144
	"""link a version to its project. A version is necessarily linked to one and only one project.
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   145
	"""
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   146
	permissions = {'read':   ('managers', 'users', 'guests',),
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   147
		       'delete': ('managers', ),
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   148
		       'add':    ('managers', 'logilab',
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   149
				  RRQLExpression('O require_permission P, P name "add_version",'
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   150
						 'U in_group G, P require_group G'),)
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   151
		       }
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   152
	inlined = True
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   153
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   154
This configuration indicates that an entity `EPermission` named
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   155
"add_version" can be associated to a project and provides rights to create
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   156
new versions on this project to specific groups. It is important to notice that :
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   157
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   158
* in such case, we have to protect both the entity type "Version" and the relation
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   159
  associating a version to a project ("version_of")
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   160
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   161
* because of the genricity of the entity type `EPermission`, we have to execute
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   162
  a unification with the groups and/or the states if necessary in the expression
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   163
  ("U in_group G, P require_group G" in the above example)
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   164
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   165
Use of RQL expression for reading rights
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   166
````````````````````````````````````````
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   167
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   168
The principles are the same but with the following restrictions :
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   169
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   170
* we can not use `RRQLExpression` on relation types for reading
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   171
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   172
* special relations "has_<ACTION>_permission" can not be used
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   173
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   174
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   175
Note on the use of RQL expression for `add` permission
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   176
``````````````````````````````````````````````````````
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   177
Potentially, the use of an RQL expression to add an entity or a relation
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   178
can cause problems for the user interface, because if the expression uses
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   179
the entity or the relation to create, then we are not able to verify the 
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   180
permissions before we actually add the entity (please note that this is
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   181
not a problem for the RQL server at all, because the permissions checks are
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   182
done after the creation). In such case, the permission check methods 
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   183
(check_perm, has_perm) can indicate that the user is not allowed to create 
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   184
this entity but can obtain the permission. 
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   185
To compensate this problem, it is usually necessary, for such case,
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   186
to use an action that reflects the schema permissions but which enables
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   187
to check properly the permissions so that it would show up if necessary.
b86448eaed66 [doc] reduce the depth of the table of contents to get latex generation working
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   188