[[TOC]]
= OrgAuth =

'''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.

== Realms ==

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 are called the '''realm''' of this person entity.

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.

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.

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". 

== Restriction Level ==

||'''Policy'''||'''Role assignments are restricted to'''||
||6||the realm of a person entity||
||7||the realm of a person entity including the realms of any of its organisation units||
||8||the realm of a person entity including the realms of any of its organisation units (+can be delegated)||

== Extended Record Ownership ==

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:

{{{
s3db.configure(tablename,
               owner_entity = function_or_lambda)
}}}

The hook function must accept {{{(table, row)}}} as parameters, and return the pe_id (Person Entity ID) of the owner entity.

It is possible to set a global default for the owner_entity hook in the config.py of the respective template:
{{{
settings.auth.owner_entity = function
}}}

'''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 global hook function.

== Extended Restriction of Access ==

Any role of a user is always only applied to the realms the role is restricted to.

  That is, the user can exercise permissions of role X only on the records of the entity he has this role '''for'''. E.g. a user who is "HR Manager" for OrgA can exercise the "HR Manager" permissions only on records "owned" by OrgA.

If there is no restriction in the role assignment (for_pe=0), then the role applies for all records regardless of their owner entity (=site-wide role).

The AUTHENTICATED, ANONYMOUS and ADMIN roles can not be restricted to realms, i.e. the permissions of these roles always apply for all records.

  '''NOTE:''' It is possible to define a ''dynamic realm'' in a role assignment (for_pe=None). This dynamic realm is the realm of all entities the user is directly affiliated with at the time of the request. This practice can though be dangerous and may be inappropriate for most multi-tenancy settings, because the user would automatically receive this role for any entity they will ever join in future - without that entity being anyhow in control of this. However, in certain deployments, this may still be convenient.
== Delegations of Permissions ==

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".

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.

Example:

  - 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.

'''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.