[[PageOutline]] = [source:sandbox/pycon/security Security Sandbox] = '' '''Warning:''' this page was used as a scratch pad during the development of the fine grained permissions for Trac. This is by no means the latest documentation for this feature, see rather the '''TracFineGrainedPermissions''' page for that, or, for plugin developers, have a look at ["TracDev/ApiChanges/0.11#IPermissionPolicy"].'' - '''This branch has been integrated into trunk as of r5514.''' - **further development ideas can now be found in Proposals/EvenFinerGrainedPermissions** ---- This sandbox aims at adding a finer grained control for the TracPermissions system. * Some related tickets: #654, #834, #948, #1316 ''TODO [milestone:0.11]'': - check the status of above tickets - update the TracPermissions page to link to fine grained permissions - integrate the FineGrainedPermissions page (#3636) * focus that page on the new pluggable security features * keep the SVN authz specific stuff in a secondary chapter, hinting that this will become a specific security policy in [milestone:0.12] The permission policy system has been [source:sandbox/pycon/security rewritten] on top of the ''[WikiContext Context]'' objects. The Wiki system, a significant part of the Ticket system and the attachment subsystem are now using the new permission policy engine. * View the revision [log:sandbox/pycon/security log] * See [diff:trunk//sandbox/pycon/security differences] for Trac [milestone:0.11]dev * See [diff:trunk@3353//sandbox/pycon/security@3354 patch] for Trac [milestone:0.10]dev (initial implementation) == 1000 ' View == * Add an interface (`IPermissionPolicy`) for checking a users permission to access [WikiContext Trac resources]. * Convert the current permission system to a plugin (`DefaultPermissionPolicy`). * Modify `PermissionCache` to cache the fine-grained policy check results (still needs some cleanup). * Convert each module to use fine-grained permissions (only the Wiki module has been converted so far). * API is backwards compatible. * Security policies can be "stacked". == API == === Using the new permission system === While the new permission system is completely backwards compatible, to make full use of it you will need to change your permission checks. Old style: {{{ #!python # Check for permission if 'WIKI_MODIFY' in req.perm: ... # Assert that user has permission req.perm.require('WIKI_MODIFY') }}} New style is based on adding a resource descriptor (`trac.resource.Resource`) as identification in permission checks: {{{ #!python # Check for permission, explicitly providing the realm ("wiki"), id # ("WikiStart") and version ("20"). All of these are optional but you must # provide all components up to the most specific you require. eg. if you # wish to restrict 'WikiStart' you must provide ('wiki', 'WikiStart'). if 'WIKI_MODIFY' in req.perm('wiki', 'WikiStart', 20): ... # A resource descriptor can be created and reused for the purpose. page_resource = Resource('wiki', 'WikiStart', 20) if 'WIKI_MODIFY' in req.perm(page_resource): ... # Assert that user has permission req.perm(page_resource).require('WIKI_MODIFY') # or ... req.perm(page_resource).require('WIKI_MODIFY') }}} === Implementing a custom security policy === Your plugin must implement this interface: {{{ #!python class IPermissionPolicy(Interface): """A security policy provider used for fine grained permission checks.""" def check_permission(action, username, resource, perm): """Check that the action can be performed by username on the resource ... }}} See `trac.perm.IPermissionPolicy` source code for much more information. == Testing the features == An example policy based on an Authz-style system has been added. See [source:trunk/sample-plugins/permissions/authz_policy.py] for details. (See also [source:trunk/sample-plugins/permissions] for more samples.) - Install [http://www.voidspace.org.uk/python/configobj.html ConfigObj] (required). - Copy this file in your plugins directory - Plonk a [http://swapoff.org/files/authzpolicy.conf authzpolicy.conf] file somewhere. - Update your `trac.ini`: {{{ [trac] ... permission_policies = AuthzPolicy, DefaultPermissionPolicy [authz_policy] authz_file = /some/trac/env/conf/authzpolicy.conf [components] ... authz_policy = enabled }}} - Finally, restart your web server. 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). For example, if the authz_file contains: {{{ [wiki:WikiStart@*] * = VIEW [wiki:PrivatePage@*] john = VIEW * = }}} and the default permissions are set like this: {{{ john WIKI_VIEW jack WIKI_VIEW # anonymous has no WIKI_VIEW }}} 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 ---- See also: TracFineGrainedPermissions, WikiContext