[[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.'' - '''This branch has been integrated into trunk as of r5514.''' - '''TODO: this page needs to be updated to the post- context refactoring status''' 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