31 | | |
32 | | - Install [http://www.voidspace.org.uk/python/configobj.html ConfigObj] (required). |
33 | | - Copy authz_policy.py into your plugins directory. |
34 | | - 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. |
35 | | - Update your `trac.ini`: |
36 | | 1. modify the [TracIni#trac-section permission_policies] entry in the `[trac]` section |
| 32 | ==== Configuration ==== |
| 33 | * Install [http://www.voidspace.org.uk/python/configobj.html ConfigObj] (still needed for 0.12). |
| 34 | * Copy authz_policy.py into your plugins directory (only for Trac 0.11). |
| 35 | * 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. |
| 36 | * Update your `trac.ini`: |
| 37 | 1. modify the [TracIni#trac-section permission_policies] entry in the `[trac]` section |
60 | | A policy will return either `True`, `False` or `None` for a given permission check. |
61 | | Only if the return value is `None` will the ''next'' permission policy be consulted. |
62 | | If no policy explicitly grants the permission, the final result will be `False` |
63 | | (i.e. no permission). |
| 63 | 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. |
| 64 | |
| 65 | NOTE: Only if the return value is `None` will the ''next'' permission policy be consulted. |
| 66 | If none of the policies explicitly grants the permission, the final result will be `False` |
| 67 | (i.e. permission denied). |
| 68 | |
| 69 | The `authzpolicy.conf` file is a `.ini` style configuration file: |
| 70 | {{{ |
| 71 | [wiki:PrivatePage@*] |
| 72 | john = WIKI_VIEW, !WIKI_MODIFY |
| 73 | jack = WIKI_VIEW |
| 74 | * = |
| 75 | }}} |
| 76 | * Each section of the config is a glob pattern used to match against a Trac resource |
| 77 | descriptor. These descriptors are in the form: |
| 78 | {{{ |
| 79 | <realm>:<id>@<version>[/<realm>:<id>@<version> ...] |
| 80 | }}} |
| 81 | Resources are ordered left to right, from parent to child. If any |
| 82 | component is inapplicable, `*` is substituted. If the version pattern is |
| 83 | not specified explicitely, all versions (`@*`) is added implicitly |
| 84 | |
| 85 | Example: Match the WikiStart page |
| 86 | {{{ |
| 87 | [wiki:*] |
| 88 | [wiki:WikiStart*] |
| 89 | [wiki:WikiStart@*] |
| 90 | [wiki:WikiStart] |
| 91 | }}} |
| 92 | |
| 93 | Example: Match the attachment `wiki:WikiStart@117/attachment/FOO.JPG@*` |
| 94 | on WikiStart |
| 95 | {{{ |
| 96 | [wiki:*] |
| 97 | [wiki:WikiStart*] |
| 98 | [wiki:WikiStart@*] |
| 99 | [wiki:WikiStart@*/attachment/*] |
| 100 | [wiki:WikiStart@117/attachment/FOO.JPG] |
| 101 | }}} |
| 102 | |
| 103 | * Sections are checked against the current Trac resource descriptor '''IN ORDER''' of |
| 104 | appearance in the configuration file. '''ORDER IS CRITICAL'''. |
| 105 | |
| 106 | * Once a section matches, the current username is matched against the keys |
| 107 | (usernames) of the section, '''IN ORDER'''. |
| 108 | * If a key (username) is prefixed with a `@`, it is treated as a group. |
| 109 | * If a value (permission) is prefixed with a `!`, the permission is |
| 110 | denied rather than granted. |
| 111 | |
| 112 | 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 || |
82 | | - All versions of WikiStart will be viewable by everybody (including anonymous) |
83 | | - !PrivatePage will be viewable only by john |
84 | | - other pages will be viewable only by john and jack |
85 | | |
| 131 | * All versions of WikiStart will be viewable by everybody (including anonymous) |
| 132 | * !PrivatePage will be viewable only by john |
| 133 | * other pages will be viewable only by john and jack |
| 134 | |
| 135 | Groups: |
| 136 | {{{ |
| 137 | [groups] |
| 138 | admins = john, jack |
| 139 | devs = alice, bob |
| 140 | |
| 141 | [wiki:Dev@*] |
| 142 | @admins = TRAC_ADMIN |
| 143 | @devs = WIKI_VIEW |
| 144 | * = |
| 145 | |
| 146 | [*] |
| 147 | @admins = TRAC_ADMIN |
| 148 | * = |
| 149 | }}} |
| 150 | |
| 151 | Then: |
| 152 | - everything is blocked (whitelist approach), but |
| 153 | - admins get all TRAC_ADMIN everywhere and |
| 154 | - devs can view wiki pages. |
| 155 | |
| 156 | Some repository examples (Browse Source specific): |
| 157 | {{{ |
| 158 | # A single repository: |
| 159 | [repository:test_repo@*] |
| 160 | john = BROWSER_VIEW, FILE_VIEW |
| 161 | # John has BROWSER_VIEW and FILE_VIEW for the entire test_repo |
| 162 | |
| 163 | # All repositories: |
| 164 | [repository:*@*] |
| 165 | jack = BROWSER_VIEW, FILE_VIEW |
| 166 | # John has BROWSER_VIEW and FILE_VIEW for all repositories |
| 167 | }}} |
| 168 | |
| 169 | Very fine grain repository access: |
| 170 | {{{ |
| 171 | # John has BROWSER_VIEW and FILE_VIEW access to trunk/src/some/location/ only |
| 172 | [repository:test_repo@*/source:trunk/src/some/location/*@*] |
| 173 | john = BROWSER_VIEW, FILE_VIEW |
| 174 | |
| 175 | |
| 176 | # John has BROWSER_VIEW and FILE_VIEW access to only revision 1 of all files at trunk/src/some/location only |
| 177 | [repository:test_repo@*/source:trunk/src/some/location/*@1] |
| 178 | john = BROWSER_VIEW, FILE_VIEW |
| 179 | |
| 180 | |
| 181 | # John has BROWSER_VIEW and FILE_VIEW access to all revisions of 'somefile' at trunk/src/some/location only |
| 182 | [repository:test_repo@*/source:trunk/src/some/location/somefile@*] |
| 183 | john = BROWSER_VIEW, FILE_VIEW |
| 184 | |
| 185 | |
| 186 | # John has BROWSER_VIEW and FILE_VIEW access to only revision 1 of 'somefile' at trunk/src/some/location only |
| 187 | [repository:test_repo@*/source:trunk/src/some/location/somefile@1] |
| 188 | john = BROWSER_VIEW, FILE_VIEW |
| 189 | }}} |
| 190 | |
| 191 | Note: In order for Timeline to work/visible for John, we must add CHANGESET_VIEW to the above permission list. |
| 192 | |
| 193 | |
| 194 | ==== Missing Features ==== |
| 195 | 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]). |
| 196 | |
| 197 | You cannot do the following: |
| 198 | {{{ |
| 199 | [groups] |
| 200 | team1 = a, b, c |
| 201 | team2 = d, e, f |
| 202 | team3 = g, h, i |
| 203 | departmentA = team1, team2 |
| 204 | }}} |
| 205 | |
| 206 | Permission groups are not supported either. You cannot do the following: |
| 207 | {{{ |
| 208 | [groups] |
| 209 | permission_level_1 = WIKI_VIEW, TICKET_VIEW |
| 210 | permission_level_2 = permission_level_1, WIKI_MODIFY, TICKET_MODIFY |
| 211 | [*] |
| 212 | @team1 = permission_level_1 |
| 213 | @team2 = permission_level_2 |
| 214 | @team3 = permission_level_2, TICKET_CREATE |
| 215 | }}} |