Changes between Version 9 and Version 10 of S3/S3AAA/OrgAuth


Ignore:
Timestamp:
09/03/12 13:42:09 (9 years ago)
Author:
Dominic König
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • S3/S3AAA/OrgAuth

    v9 v10  
    22= OrgAuth =
    33
    4 '''OrgAuth''' are two special authorisation policies based on policy 5 (table-level permissions), with the additional restriction of access permissions to records of particular organisations/facilities.
     4'''OrgAuth''' are special authorisation policies based on policy 5 (table-level permissions), with the additional restriction of access permissions to particular records based on realms.
     5
     6== Realms ==
     7
     8Records can be "owned" by person entities (organisations, offices, teams, persons etc.). This is implemented as an additional meta-field "owned_by_entity", which takes a pe_id (Person Entity ID). All records "owned" by a person entity that way are called the '''realm''' of this person entity.
     9
     10In OrgAuth policies, any role assignment for a user (and thus all the permissions the user receives out of the respective role) can be restricted to a realm.
     11
     12In policy 7 and above, realms are hierarchical. That is, the realm of an entity includes all the realms of all organisation units (OU) of this entity.
     13
     14In policy 8, person entities can allow other person entities (and any of their organisation units) to access their realm with the permissions of a certain role. This mechanism is called "delegation".
    515
    616== Restriction Level ==
    717
    818||'''Policy'''||'''Permissions are restricted to'''||
    9 ||6||records of particular organisations||
    10 ||7||records of particular facilities of particular organisations||
     19||6||the realm of a person entity||
     20||7||the realm of a person entity and of any of its organisation units||
     21||8||the realm of a person entity and of any of its organisation units, and delegated realms||
    1122
    1223== Extended Record Ownership ==
    1324
    14 Every organisation and every facility has an access role (auth_group entry) assigned.
     25The "owned_by_entity" field get automatically populated in CRUD and Imports, using the auth.set_record_owner method. This method can be influenced by the '''owner_entity''' table hook:
    1526
    16 These access roles are created when the respective organisation/facility record is created, and their role-UUIDs are prefixed by either "Org_" (for organisations) or "Fac_" (for facilities). This happens automatically in CRUD and XML imports (by auth.set_record_owner())
     27{{{
     28s3db.configure(tablename,
     29               owner_entity = function_or_lambda)
     30}}}
    1731
    18 Every record with an ''organisation_id'' or ''site_id'' link automatically gets these roles set for:
     32The hook function must accept {{{(table, row)}}} as parameters, and return the pe_id (Person Entity ID) of the owner entity.
    1933
    20   - owned_by_organisation
    21   - owned_by_facility
     34It is possible to set a global default for the owner_entity hook in the config.py of the respective template:
     35{{{
     36settings.auth.owner_entity = function
     37}}}
    2238
    23 This happens automatically in CRUD and XML imports (by auth.set_record_owner()).
    24 
    25 To own a record, the user must either own the record as individual (owned_by_user) or have the owner role (owned_by_role). In OrgAuth policies, the user must additionally have the access role of the owner organisation (owned_by_organisation, policy 6) or both the access role of the owner organisation ''and'' of the owner facility (owned_by_organisation+owned_by_facility, policy 7).
     39'''NOTE:''' the global owner_entity setting overrides any table-specific setting (this is deliberate), i.e. to retain a table specific setting, you must repeat it in the hook function.
    2640
    2741== Extended Restriction of Access ==
    2842
    29 In OrgAuth, any applicable ACL is automatically restricted to the records of those organisations (policy 6) or organisations+facilities (policy 7) for which the user has the respective access roles. This applies to both, user-ACLs (uacl) and owner-ACLs (oacl).
     43Any role of a user are always only applied to the realms the role is restricted to.
    3044
    31 It is possible to override this restriction in the ACL itself, and explicitly define for which organisation/facility the ACL shall apply (see [#DelegationsofPermissions Delegations of Permissions]), or to define that the ACL shall apply for the records of ''all'' organisations/facilities (see [#GeneralDelegationsofPermissions General Delegations of Permissions]).
     45If there is no restriction in the role assignment, then the role applies for all records regardless of their owner entity (=site-wide role).
     46
     47The AUTHENTICATED, ANONYMOUS and ADMIN roles can not be restricted to realms, i.e. the permissions of these roles always apply for all records.
    3248
    3349== Delegations of Permissions ==
    3450
    35 In OrgAuth policies, any applicable ACL is automatically restricted to the record of those organisations/facilities for which the user has the respective access roles.
     51A person entity can allow another entity to access records within their realm with the permissions of a certain user role. This is called "delegation".
    3652
    37 It is however possible to override this and define explicitly which organisation/facility the ACL shall apply for:
     53All users which are affiliated with the other entity (or any of its organisation units) can then exercise the permissions of the delegated role on the realm of the delegating entity provided they would have the same permissions for the realm of the other entity.
    3854
    39 Delegation of permissions to a user group (e.g. anonymous users, all authenticated users...):
     55Example:
    4056
    41 {{{
    42     # Get the access role from the organisation record
    43     org_record = db(db.org_organisation.id == my_org_id).select(db.org_organisation.owned_by_organisation,
    44                                                                 limitby=(0, 1)).first()
     57  - if OrgA allows OrgB to access their realm with the "HR Editor" role, then all users affiliated with OrgB are permitted to edit human resource records of OrgA ''if'' they are permitted to edit human resource records for OrgB.
    4558
    46     # Delegate read permission for this organisation's inv_inv_item record to all authenticated users
    47     update_acls(authenticated,
    48                 dict(t="inv_inv_item", uacl=acl.READ, organisation=org_record.owned_by_organisation))
    49 }}}
    50 
    51 Can also delegate to another organisation:
    52 
    53 {{{
    54     # Get the access role for this organisation
    55     this_org = db(db.org_organisation.id == my_org_id).select(db.org_organisation.owned_by_organisation,
    56                                                               limitby=(0, 1)).first()
    57 
    58     # Get the access role for the other organisation
    59     other_org = db(db.org_organisation.id == other_org_id).select(db.org_organisation.owned_by_organisation,
    60                                                                   limitby=(0, 1)).first()
    61 
    62     # Delegate read permission for this organisation's inv_inv_item record to all authenticated users
    63     update_acls(other_org.owned_by_role,
    64                 dict(t="inv_inv_item", uacl=acl.READ, organisation=this_org.owned_by_organisation))
    65 }}}
    66 
    67 == General Delegations of Permissions ==
    68 
    69 In OrgAuth policies, any applicable ACL is automatically restricted to the record of those organisations/facilities for which the user has the respective access roles.
    70 
    71 This can be overridden in the ACL itself to make the ACL apply for the records of ''all'' organisations/facilities:
    72 
    73 Delegate READ permission on inv_inv_item record of ''all'' organisations to a user group:
    74 
    75 {{{
    76     update_acls(authenticated,
    77                 dict(t="inv_inv_item", uacl=acl.READ, entity="any"))
    78 }}}
    79 
    80 == Organisation-dependent Role Assignments ==
    81 
    82 It is currently not yet possible to have a role of the user only apply for the access to records of a particular organisation/facility.
    83 
    84 If the user has a role, then this role applies for the access to records in ''any'' organisation/facility.
    85 
    86 This is subject to change in future.
     59'''NOTE:''' Delegations are not personal. If a user is no longer affiliated with the receiving entity, they can not receive permissions out of the delegations to this entity anymore - and vice versa. For personal delegations, it is better to use a direct role assignment for the realm of the delegating entity.