changeset 192:ef9ec0e2a85e

docs: AccessControlLists
author Thomas Waldmann <tw AT waldmann-edv DOT de>
date Sun, 24 Apr 2011 19:39:49 +0200
parents 49d1c9f7a9c0
children 17693a043442
files docs/admin/configure.rst
diffstat 1 files changed, 127 insertions(+), 13 deletions(-) [+]
line wrap: on
line diff
--- a/docs/admin/configure.rst	Sun Apr 24 17:40:15 2011 +0200
+++ b/docs/admin/configure.rst	Sun Apr 24 19:39:49 2011 +0200
@@ -559,8 +559,7 @@
 that means that they are rather open and give freedom to the users, while
 providing means to revert damage in case it happens.
 
-*Hard security* means to lock down everything, so that users are not able
-to do anything without being allowed to.
+*Hard security* means to lock stuff so that no damage can happen.
 
 Moin's default configuration tries to give a sane compromise of both soft
 and hard security. But, depending on the situation the wiki
@@ -595,9 +594,9 @@
   won't get questions to answer. Give this to known and trusted users who
   regularly edit in your wiki.
 
-ACLs for content
-----------------
-These ACLs control access to content stored in the wiki - they are configured
+ACLs for contents
+-----------------
+These ACLs control access to contents stored in the wiki - they are configured
 per storage backend (see also there) and (optionally) in the metadata of wiki
 items::
 
@@ -620,6 +619,14 @@
    "before" -> "item acl from metadata (if specified)" -> "after";
    "before" -> "default (otherwise)"                   -> "after";
 
+How to use before/default/after:
+
+* `before` is usually used to force stuff (e.g. if you want to give some
+  wiki admin all permissions no matter what)
+* `default` is behaviour if nothing special has been specified (no ACL in
+  item metadata)
+* `after` is (rarely) used to "not forget something unless otherwise specified".
+
 When configuring content ACLs, you can choose between standard (flat) ACL
 processing and hierarchic ACL processing. Hierarchic processing means that
 subitems inherit ACLs from their parent items if they have no own ACL.
@@ -634,17 +641,124 @@
 * read - read content
 * write - write (edit, modify) content
 * create - create new items
-* destroy - completely destroy revisions or items (never give to not fully
-  trusted users)
-* admin - change (create, remove) ACLs for the item (never give to not fully
-  trusted users)
+* destroy - completely destroy revisions or items (never give this to not
+  fully trusted users)
+* admin - change (create, remove) ACLs for the item (never give this to not
+  fully trusted users)
 
-ACL syntax
-----------
+ACLs - special groups
+---------------------
+Additionally to the groups provided by the group backend(s), there are some
+special group names available within ACLs:
 
-.. todo::
+* All - a virtual group containing every user
+* Known - a virtual group containing every logged-in user
+* Trusted - a virtual group containing every logged-in user, who was logged
+  in by some specific "trusted" authentication methods
 
-   reuse content from HelpOnAccessControlLists
+
+ACLs - basic syntax
+-------------------
+An ACL is a (unicode) string with one or multiple access control entries
+(space separated).
+
+An entry has:
+
+* a left side with user and/or group names (comma separated)
+* a colon ':' as separator and
+* a right side with rights / capabilities (comma separated).
+
+An ACL is processed from left to right, first left-side match counts.
+
+Example::
+
+    u"SuperMan:read,write,create,destroy,admin All:read,write"
+
+If "SuperMan" is currently logged in and moin processes this ACL, it'll find
+a name match in the first entry. If moin wants to know whether he may destroy,
+the answer will be "yes", as destroy is one of the capabilities/rights listed
+on the right side of this entry.
+
+If "JoeDoe" is currently logged in and moin processes this ACL, the first entry
+won't match, so moin will proceed left-to-right and look at the second entry.
+Here we have the special group name "All" (and JoeDoe obviously is a member of
+this group), so we have a match here.
+If moin wants to know whether he may destroy, the answer will be "no", as
+destroy is not listed on the right side of this entry. If moin wants to know
+whether he may write, the answer will be "yes".
+
+Notes:
+
+* As a consequence of the left-to-right and first-match-counts processing,
+  you must order ACL entries so that the more specific ones (like for
+  "SuperMan") are left of the less specific ones.
+  Usually you want this order:
+
+  1) usernames
+  2) special groups
+  3) more general groups
+  4) Trusted
+  5) Known
+  6) All
+
+* Do not put any spaces into an ACL entry (except if it is part of a user or
+  group name)
+
+* A right that is not explicitly given by an applicable ACL is denied.
+
+* For most ACLs there are builtin defaults, which give some rights.
+
+ACLs - entry prefixes
+---------------------
+To make the system more flexible, there are also two ACL entry modifiers: the prefixes '+' and '-'.
+
+If you use them, matches will have to be left-side *and* right-side (otherwise
+it will just continue with the next entry).
+
+'+' means to give the permission(s) specified on the right side.
+
+'-' means to deny the permission(s) specified on the right side.
+
+Example::
+
+    u"+SuperMan:create,destroy,admin -Idiot:write All:read,write"
+
+If "SuperMan" is currently logged in and moin wants to know whether he may
+destroy, it'll find a match in the first entry (name matches *and* permission
+in question matches). As the prefix is '+', the answer is "yes".
+If moin wants to know whether he may write, the first entry will not match
+on both sides, so moin will proceed and look at the second entry. It doesn't
+match, so it'll look at the third entry. Of course "SuperMan" is a member of
+group "All", so we have a match here. As "write" is listed on the right side,
+the answer will be "yes".
+
+If "Idiot" is currently logged in and moin wants to know whether he may write,
+it'll find no match in the first entry, but the second entry will match. As
+the prefix is '-', the answer will be "no" (and it will not even proceed and
+look at the third entry).
+
+Notes:
+
+* you usually use these modifiers if most of the rights shall be as specified
+  later, but a special user or group should be treated slightly different for
+  a few special rights.
+
+ACLs - Default entry
+--------------------
+There is a special ACL entry "Default" which expands itself in-place to the
+default ACL.
+
+This is useful if e.g. for some items you mostly want the default ACL, but
+with a slight modification - but you don't want to type in the default ACL
+all the time (and you also want to be able to change the default ACL without
+having to edit lots of items).
+
+Example::
+
+    u"-NotThisGuy:write Default"
+
+This will behave as usual, except that "NotThisGuy" will never be given write
+permission.
 
 
 Anti-Spam