Changes between Version 2 and Version 3 of TracFineGrainedPermissions

Timestamp:

01/19/14 16:40:14 (12 years ago)

Author:

trac

Comment:

--

TracFineGrainedPermissions

@@ +1 @@
+[[PageOutline(2-5, Contents, floated)]]
 = Fine grained permissions =
 
@@ -29 +30 @@
 
 === !AuthzPolicy === 
-
- - Install [http://www.voidspace.org.uk/python/configobj.html ConfigObj] (required).
- - Copy authz_policy.py into your plugins directory.
- - Put a [http://swapoff.org/files/authzpolicy.conf authzpolicy.conf] file somewhere, preferably on a secured location on the server, not readable for others than the webuser. If the  file contains non-ASCII characters, the UTF-8 encoding should be used.
- - Update your `trac.ini`:
-   1. modify the [TracIni#trac-section permission_policies] entry in the `[trac]` section
+==== Configuration ====
+* Install [http://www.voidspace.org.uk/python/configobj.html ConfigObj] (still needed for 0.12).
+* Copy authz_policy.py into your plugins directory (only for Trac 0.11).
+* Put a [http://swapoff.org/files/authzpolicy.conf authzpolicy.conf] file somewhere, preferably on a secured location on the server, not readable for others than the webuser. If the  file contains non-ASCII characters, the UTF-8 encoding should be used.
+* Update your `trac.ini`:
+  1. modify the [TracIni#trac-section permission_policies] entry in the `[trac]` section
 {{{
 [trac]
@@ -40 +41 @@
 permission_policies = AuthzPolicy, DefaultPermissionPolicy, LegacyAttachmentPolicy
 }}}
-   2. add a new `[authz_policy]` section
+  1. add a new `[authz_policy]` section
 {{{
 [authz_policy]
 authz_file = /some/trac/env/conf/authzpolicy.conf
 }}}
-   3. enable the single file plugin
+  1. enable the plugin through [/admin/general/plugin WebAdmin] or by editing the `[components]` section
 {{{
 [components]
@@ -55 +56 @@
 }}}
 
+
+==== Usage Notes ====
 Note that the order in which permission policies are specified is quite critical, 
 as policies will be examined in the sequence provided.
 
-A policy will return either `True`, `False` or `None` for a given permission check.
-Only if the return value is `None` will the ''next'' permission policy be consulted.
-If no policy explicitly grants the permission, the final result will be `False` 
-(i.e. no permission).
+A policy will return either `True`, `False` or `None` for a given permission check. `True` is returned if the policy explicitly grants the permission. `False` is returned if the policy explicitly denies the permission. `None` is returned if the policy is unable to either grant or deny the permission.
+
+NOTE: Only if the return value is `None` will the ''next'' permission policy be consulted.
+If none of the policies explicitly grants the permission, the final result will be `False` 
+(i.e. permission denied).
+
+The `authzpolicy.conf` file is a `.ini` style configuration file:
+{{{
+[wiki:PrivatePage@*]
+john = WIKI_VIEW, !WIKI_MODIFY
+jack = WIKI_VIEW
+* =
+}}}
+* Each section of the config is a glob pattern used to match against a Trac resource
+  descriptor. These descriptors are in the form:
+{{{
+<realm>:<id>@<version>[/<realm>:<id>@<version> ...]
+}}}
+  Resources are ordered left to right, from parent to child. If any
+  component is inapplicable, `*` is substituted. If the version pattern is
+  not specified explicitely, all versions (`@*`) is added implicitly
+
+  Example: Match the WikiStart page
+{{{
+[wiki:*]
+[wiki:WikiStart*]
+[wiki:WikiStart@*]
+[wiki:WikiStart]
+}}}
+
+  Example: Match the attachment `wiki:WikiStart@117/attachment/FOO.JPG@*`
+  on WikiStart
+{{{
+[wiki:*]
+[wiki:WikiStart*]
+[wiki:WikiStart@*]
+[wiki:WikiStart@*/attachment/*]
+[wiki:WikiStart@117/attachment/FOO.JPG]
+}}}
+
+* Sections are checked against the current Trac resource descriptor '''IN ORDER''' of
+  appearance in the configuration file. '''ORDER IS CRITICAL'''.
+
+* Once a section matches, the current username is matched against the keys 
+  (usernames) of the section, '''IN ORDER'''. 
+  * If a key (username) is prefixed with a `@`, it is treated as a group. 
+  * If a value (permission) is prefixed with a `!`, the permission is
+    denied rather than granted.
+
+  The username will match any of 'anonymous', 'authenticated', <username> or '*', using normal Trac permission rules. || '''Note:''' Other groups which are created by user (e.g. by 'adding subjects to groups' on web interface page //Admin / Permissions//) cannot be used. See [trac:ticket:5648 #5648] for details about this missing feature ||
 
 For example, if the `authz_file` contains:
@@ -70 +119 @@
 [wiki:PrivatePage@*]
 john = WIKI_VIEW
-* =
+* = !WIKI_VIEW
 }}}
 and the default permissions are set like this:
@@ -80 +129 @@
 
 Then: 
- - All versions of WikiStart will be viewable by everybody (including anonymous)
- - !PrivatePage will be viewable only by john
- - other pages will be viewable only by john and jack
-
+  * All versions of WikiStart will be viewable by everybody (including anonymous)
+  * !PrivatePage will be viewable only by john
+  * other pages will be viewable only by john and jack
+
+Groups:
+{{{
+[groups]
+admins = john, jack
+devs = alice, bob
+
+[wiki:Dev@*]
+@admins = TRAC_ADMIN
+@devs = WIKI_VIEW
+* =
+
+[*]
+@admins = TRAC_ADMIN
+* =
+}}}
+
+Then:
+- everything is blocked (whitelist approach), but
+- admins get all TRAC_ADMIN everywhere and
+- devs can view wiki pages.
+
+Some repository examples (Browse Source specific):
+{{{
+# A single repository:
+[repository:test_repo@*]
+john = BROWSER_VIEW, FILE_VIEW
+# John has BROWSER_VIEW and FILE_VIEW for the entire test_repo
+
+# All repositories:
+[repository:*@*]
+jack = BROWSER_VIEW, FILE_VIEW
+# John has BROWSER_VIEW and FILE_VIEW for all repositories
+}}}
+
+Very fine grain repository access:
+{{{
+# John has BROWSER_VIEW and FILE_VIEW access to trunk/src/some/location/ only
+[repository:test_repo@*/source:trunk/src/some/location/*@*]
+john = BROWSER_VIEW, FILE_VIEW
+
+
+# John has BROWSER_VIEW and FILE_VIEW access to only revision 1 of all files at trunk/src/some/location only
+[repository:test_repo@*/source:trunk/src/some/location/*@1]
+john = BROWSER_VIEW, FILE_VIEW
+
+
+# John has BROWSER_VIEW and FILE_VIEW access to all revisions of 'somefile' at trunk/src/some/location only 
+[repository:test_repo@*/source:trunk/src/some/location/somefile@*]
+john = BROWSER_VIEW, FILE_VIEW
+
+
+# John has BROWSER_VIEW and FILE_VIEW access to only revision 1 of 'somefile' at trunk/src/some/location only
+[repository:test_repo@*/source:trunk/src/some/location/somefile@1]
+john = BROWSER_VIEW, FILE_VIEW
+}}}
+
+Note: In order for Timeline to work/visible for John, we must add CHANGESET_VIEW to the above permission list.
+
+
+==== Missing Features ====
+Although possible with the !DefaultPermissionPolicy handling (see Admin panel), fine-grained permissions still miss those grouping features (see [trac:ticket:9573 #9573], [trac:ticket:5648 #5648]). Patches are partially available, see forgotten authz_policy.2.patch  part of [trac:ticket:6680 #6680]).
+
+You cannot do the following:
+{{{
+[groups]
+team1 = a, b, c
+team2 = d, e, f
+team3 = g, h, i
+departmentA = team1, team2
+}}}
+
+Permission groups are not supported either. You cannot do the following:
+{{{
+[groups]
+permission_level_1 = WIKI_VIEW, TICKET_VIEW
+permission_level_2  = permission_level_1, WIKI_MODIFY, TICKET_MODIFY
+[*]
+@team1 = permission_level_1
+@team2 = permission_level_2
+@team3 = permission_level_2, TICKET_CREATE
+}}}
 
 === !AuthzSourcePolicy  (mod_authz_svn-like permission policy) === #AuthzSourcePolicy