Changes between Version 9 and Version 10 of S3/S3AAA/OrgAuth
- Timestamp:
- 09/03/12 13:42:09 (12 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
S3/S3AAA/OrgAuth
v9 v10 2 2 = OrgAuth = 3 3 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 8 Records 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 10 In 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 12 In 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 14 In 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". 5 15 6 16 == Restriction Level == 7 17 8 18 ||'''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|| 11 22 12 23 == Extended Record Ownership == 13 24 14 Every organisation and every facility has an access role (auth_group entry) assigned. 25 The "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: 15 26 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 {{{ 28 s3db.configure(tablename, 29 owner_entity = function_or_lambda) 30 }}} 17 31 18 Every record with an ''organisation_id'' or ''site_id'' link automatically gets these roles set for: 32 The hook function must accept {{{(table, row)}}} as parameters, and return the pe_id (Person Entity ID) of the owner entity. 19 33 20 - owned_by_organisation 21 - owned_by_facility 34 It is possible to set a global default for the owner_entity hook in the config.py of the respective template: 35 {{{ 36 settings.auth.owner_entity = function 37 }}} 22 38 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. 26 40 27 41 == Extended Restriction of Access == 28 42 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).43 Any role of a user are always only applied to the realms the role is restricted to. 30 44 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]). 45 If there is no restriction in the role assignment, then the role applies for all records regardless of their owner entity (=site-wide role). 46 47 The AUTHENTICATED, ANONYMOUS and ADMIN roles can not be restricted to realms, i.e. the permissions of these roles always apply for all records. 32 48 33 49 == Delegations of Permissions == 34 50 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.51 A person entity can allow another entity to access records within their realm with the permissions of a certain user role. This is called "delegation". 36 52 37 It is however possible to override this and define explicitly which organisation/facility the ACL shall apply for: 53 All 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. 38 54 39 Delegation of permissions to a user group (e.g. anonymous users, all authenticated users...):55 Example: 40 56 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. 45 58 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.
