doc/04_security.rst

   1 ==================================
   2 Security in OpenERP: users, groups
   3 ==================================
   4
   5 Users and user roles are critical points concerning internal security in
   6 OpenERP. OpenERP provides several security mechanisms concerning user roles,
   7 all implemented in the OpenERP Server. They are implemented in the lowest
   8 server level, which is the ORM engine. OpenERP distinguishes three different
   9 concepts:
  10
  11  - user: a person identified by its login and password. Note that all employees
  12    of a company are not necessarily OpenERP users; an user is somebody who
  13    accesses the application.
  14  - group: a group of users that has some access rights. A group gives its
  15    access rights to the users that belong to the group. Ex: Sales Manager,
  16    Accountant, etc.
  17  - security rule: a rule that defines the access rights a given group grants
  18    to its users. Security rules are attached to a given resource, for example
  19    the Invoice model.
  20
  21 Security rules are attached to groups. Users are assigned to several groups.
  22 This gives users the rights that are attached to their groups. Therefore
  23 controlling user roles is done by managing user groups and adding or modifying
  24 security rules attached to those groups.
  25
  26 Users
  27 ======
  28
  29 Users represent physical persons using OpenERP. They are identified with
  30 a login and a password,they use OpenERP, they can edit their own preferences, ...
  31 By default, a user has no access right. The more we assign groups to the user,
  32 the more he or she gets rights to perform some actions. A user may belong
  33 to several groups.
  34
  35 User groups
  36 ===========
  37
  38 The groups determine the access rights to the different resources. A user
  39 may belong to several groups. If he belongs to several groups, we always
  40 use the group with the highest rights for a selected resource. A group
  41 can inherit all the rights from another group
  42
  43 Figure 3 shows how group membership is displayed in the web client. The user
  44 belongs to Sales / Manager, Accounting / Manager, Administration / Access Rights,
  45 Administration / Configuration and Human Resources / Employee groups. Those
  46 groups define the user access rights.
  47
  48 Figure 3: Example of group membership for a given user
  49
  50 Rights
  51 ======
  52
  53 Security rules are attached to groups. You can assign several security
  54 rules at the group level, each rule being of one of the following types :
  55
  56  - access rights are global rights on an object,
  57  - record rules are records access filters,
  58  - fields access right,
  59  - workflow transition rules are operations rights.
  60
  61 You can also define rules that are global, i.e. they are applied to all
  62 users, indiscriminately of the groups they belong to. For example, the
  63 multi-company rules are global; a user can only see invoices of the companies
  64 he or she belongs to.
  65
  66
  67 Concerning configuration, it is difficult to have default generic configurations
  68 that suit all applications. Therefore, like SAP, OpenERP is by default
  69 pre-configured with best-practices.
  70
  71 Access rights
  72 =============
  73
  74 Access rights are rules that define the access a user can have on a particular
  75 object . Those global rights are defined per document type or model. Rights
  76 follow the CRUD model: create, read (search), update (write), delete. For
  77 example, you can define rules on invoice creation. By default, adding a
  78 right to an object gives the right to all records of that specific object.
  79
  80 Figure 4 shows some of the access rights of the Accounting / Accountant group.
  81 The user has some read access rights on some objects.
  82
  83 Figure 4: Access rights for some objects.
  84
  85 Record rules
  86 ++++++++++++
  87
  88 When accessing an object, records are filtered based on record rules. Record
  89 rules or access filters are therefore filters that limits records of an
  90 object a group can access. A record rule is a condition that each record
  91 must satisfy to be created, read, updated (written) or deleted. Records
  92 that do not meet the constraints are filtered.
  93
  94 For example, you can create a rule to limit a group in such a way that
  95 users of that group will see business opportunities in which he or she is
  96 flagged as the salesman. The rule can be salesman = connected_user. With
  97 that rule, only records respecting the rule will be displayed.
  98
  99
 100 Field access rights
 101 +++++++++++++++++++
 102
 103 .. versionadded:: 7.0
 104
 105 OpenERP now supports real access control at the field level, not just on the view side.
 106 Previously it was already possible to set a ``groups`` attribute on a ``<field>`` element
 107 (or in fact most view elements), but with cosmetics effects only: the element was made
 108 invisible on the client side, while still perfectly available for read/write access at
 109 the RPC level.
 110
 111 As of OpenERP 7.0 the existing behavior is preserved on the view level, but a new ``groups``
 112 attribute is available on all model fields, introducing a model-level access control on
 113 each field. The syntax is the same as for the view-level attribute::
 114
 115     _columns = {
 116         'secret_key': fields.char('Secret Key', groups="base.group_erp_manager,base.group_system")
 117      }
 118
 119 There is a major difference with the view-level ``groups`` attribute: restricting
 120 the access at the model level really means that the field will be completely unavailable
 121 for users who do not belong to the authorized groups:
 122
 123 * Restricted fields will be **completely removed** from all related views, not just
 124   hidden. This is important to keep in mind because it means the field value will not be
 125   available at all on the client side, and thus unavailable e.g. for ``on_change`` calls.
 126 * Restricted fields will not be returned as part of a call to
 127   :meth:`~openerp.osv.orm.fields_get` or :meth:`~openerp.osv.orm.fields_view_get`
 128   This is in order to avoid them appearing in the list of fields available for
 129   advanced search filters, for example. This does not prevent getting the list of
 130   a model's fields by querying ``ir.model.fields`` directly, which is fine.
 131 * Any attempt to read or write directly the value of the restricted fields will result
 132   in an ``AccessError`` exception.
 133 * As a consequence of the previous item, restricted fields will not be available for
 134   use within search filters (domains) or anything that would require read or write access.
 135 * It is quite possible to set ``groups`` attributes for the same field both at the model
 136   and view level, even with different values. Both will carry their effect, with the
 137   model-level restriction taking precedence and removing the field completely in case of
 138   restriction.
 139
 140 .. note:: The tests related to this feature are in ``openerp/tests/test_acl.py``.
 141
 142 .. warning:: At the time of writing the implementation of this feature is partial
 143              and does not yet restrict read/write RPC access to the field.
 144              The corresponding test is written already but currently disabled.
 145
 146 Workflow transition rules
 147 +++++++++++++++++++++++++
 148
 149 Workflow transition rules are rules that restrict some operations to certain
 150 groups. Those rules handle rights to go from one step to another one in the
 151 workflow. For example, you can limit the right to validate an invoice, i.e.
 152 going from a draft action to a validated action.
 153
 154 Menu accesses
 155 =============
 156
 157 In OpenERP, granting access to menus can be done using user groups. A menu
 158 that is not granted to any group is accessible to every user. It is possible
 159 in the administration panel to define the groups that can access a given menu.
 160
 161 However, one should note that using groups to hide or give access to menus
 162 is more within the filed of ergonomics or usability than within the field
 163 of security. It is a best practice putting rules on documents instead of
 164 putting groups on menu. For example, hiding invoices can be done by modifying
 165 the record rule on the invoice object, and it is more efficient and safer
 166 than hiding menus related to invoices.
 167
 168 Views customization
 169 ===================
 170
 171 Customizing views based on groups is possible in OpenERP. You can put rules
 172 to display some fields based on group rules. However, as with menu accesses
 173 customization, this option should not be considered for security concerns.
 174 This way of customizing views belongs more to usability.
 175
 176 Administration
 177 ==============
 178
 179 When installing your particular instance of OpenERP, a specific first user
 180 is installed by default. This first user is the Super User or administrator.
 181 The administrator is by default added access rights to every existing groups,
 182 as well as to every groups created during a new module installation. He also
 183 has access to a specific administration interface accessible via the administration
 184 menu, allowing the administration of OpenERP.
 185
 186 The administrator has rights to manage groups; he can add, create, modify
 187 or remove groups. He may also modify links between users and groups, such
 188 as adding or removing users. He also manages access rights. With those
 189 privileges, the administrator can therefore precisely define security
 190 accesses of every users of OpenERP.
 191
 192 There are user groups that are between normal groups and the super user.
 193 Those groups are Administration / Configuration and Administration / Access Rights.
 194 It gives to the users of those groups the necessary rights to configure access rights.
 195