Peter M. Groen / knowledgetree

Commit 05b14a8beb3e27719b442b26daab84eed1c8aacc

Authored by nbm
1 parent 6e85fb54

Basic developer documentation for the new permission system. 


git-svn-id: https://kt-dms.svn.sourceforge.net/svnroot/kt-dms/trunk@3501 c91229c3-7414-0410-bfa2-8a42b809f60b
Inline Side-by-side
Showing 1 changed file with 72 additions and 0 deletions
docs/Permissions.txt 0 → 100644
  View file @05b14a8
  1 +KnowledgeTree Permission System
  2 +===============================
  3 +
  4 +Permission Object
  5 +-----------------
  6 +Permissions on items in the DMS are handled via a Permission Object.
  7 +This permission object is where the permissions for the object are kept.
  8 +Previously, a permission folder was used, but this was changed to an
  9 +autonomous permission object to allow greater flexibility - such as
  10 +allowing documents to have their own permissions in future.
  11 +
  12 +Permission Assignments
  13 +----------------------
  14 +This permission object links the item with a number of permission
  15 +assignments - one permission assignment per permission. A permission
  16 +assignment is uniquely specified by a permission object and a
  17 +permission. The final component is a permission descriptor, which
  18 +describes the groups, users, or roles that have that permission on that
  19 +permission object.
  20 +
  21 +Permission Descriptor
  22 +---------------------
  23 +The permission descriptor is an indirection to reduce the number of rows
  24 +to describe which groups, users, and roles that have permissions on each
  25 +permission object. It allows assignments that cover the same groups,
  26 +users, and roles to be described textually and looked up quickly by a 32
  27 +character hash. A particular collection of groups, users, and roles
  28 +will always be described by a unique descriptor.
  29 +
  30 +Permission Lookup
  31 +-----------------
  32 +Permission Lookup objects describe the collections of groups and users
  33 +that have each permission on the item in the repository. It is an
  34 +expanded form of the permission object - if an owner role has a
  35 +permission in terms of the permission object, the exact user with that
  36 +role on that object will be mentioned in the permission lookup.
  37 +
  38 +Permission lookups exist mostly for restricting a search for items in
  39 +the repository to those items for whom a particular user has a given
  40 +permission. The most obvious users of this are the content and metadata
  41 +searches, which need to restrict results to documents readable by the
  42 +current user. Other users may be the list of documents in a folder
  43 +readable by the current user, or the list of folders in the repository
  44 +that the user can add documents to.
  45 +
  46 +Managing Permissions
  47 +--------------------
  48 +
  49 +Permission lookups use descriptors that never expand groups. Changes in
  50 +membership of a group don't require permission lookups. When looking up
  51 +using permission lookups, the descriptors that the user has access to
  52 +are looked up at run-time first, and these are used to limit the
  53 +searches.
  54 +
  55 +On creation, folders and documents inherit the permission object of
  56 +their parent. They then update their own permission lookups.
  57 +(Document::create, Folder::create)
  58 +
  59 +When folders change their permission object (become their own master,
  60 +start using their parent again, are moved), they update all ancestor
  61 +folders and documents that had the old permission object to the new one.
  62 +Those changed then have their permission lookups updated.
  63 +(KTPermissionUtil::copyPermissionObject,
  64 +KTPermissionUtil::inheritPermissionObject)
  65 +
  66 +When documents change their permission object (become their own master,
  67 +start using their parent again, are moved), they update their own
  68 +permission lookups.
  69 +(KTPermissionUtil::copyPermissionObject,
  70 +KTPermissionUtil::inheritPermissionObject)
  71 +
  72 +