[[PageOutline(2-5,Contents,pullout)]]

= Configure permissions on tickets and wiki pages

{{{#!box info
'''Caution''': this plugin has not been fully tested, please proceed with caution!
}}}

== Description

This plugin provides configurable and powerful permission control to Trac's ticket and wiki system.

=== Custom Actions/Permissions

Supports for adding custom actions and permissions in trac.ini section {{{configurable-permission}}}.

Syntax: {{{(action_name) = enabled|disabled}}}, where:
 * (action_name): The action/permission you want to add. Will be auto capitalized in Trac.
 * enabled|disabled: Whether the action is enabled/disabled.

Examples:
{{{#!ini
[configurable-permission]
view_bug_ticket = enabled
view_bug_wiki = enabled
}}}

=== Custom permission rules/policy

Supports for adding custom permission rules to ticket and wiki system. This plugin would be useful in circumstances where more fine-grained control over what users can and cannot do to tickets or wiki pages is required.

To enable this function, first add 'ConfigurablePermissionPolicy' to {{{permission_policies}}} option, and preferably prior to DefaultPermissionPolicy. 
{{{#!ini
[trac]
permission_policies = ConfigurablePermissionPolicy,ReadonlyWikiPolicy,DefaultPermissionPolicy,LegacyAttachmentPolicy
}}}
----
The rules are configured in `[configurable-permission-rules]` section.

Syntax for a custom permission rule: {{{(rule_name) = ticket|wiki, (action), (matching_condition), (permission), (result)}}}, where:
 * `(rule_name)`: The rule name, which does not really affect the function of the rule. However, Trac will auto sort the trac.ini, and the order of rules matters, so the naming should consider sorting.
 * `ticket|wiki`: Whether the rule applies to tickets or the wiki.
 * `(action)`: What action triggers the rule. Can be set to empty or '*' to match all actions, or set to a specific action such as `TICKET_VIEW`.
 * `(matching_condition)`: Only those objects that match the conditions apply to the rule. 
  * for ticket permission rule, it can be set to empty or '*' to match all tickets, or set to a query such as 'type=bug'.
  * for wiki permission rule, it matches the name of the wiki page.
 * `(permission)`: Those users with given permission applies to the rule. Can be set to empty or '*' which means everyone. Can be used with custom permission mentioned above, such as `VIEW_BUG_TICKET`.
 * `(result)`: What will the permission system do to matched objects, can be one of the following values:
  * `allow`: Explicitly allow this action, no further policy group will be applied.
  * `allow-only`: Explicitly allow this action, and deny all other users without the given permission. No further policy group will be applied.
  * `deny`: Explicitly deny this action, No further policy group will be applied.
  * `pass`: Leave this action to further policy groups, such as DefaultPermissionPolicy. Recommended against 'allow'.
  * `pass-only`: Leave this action to further policy groups, such as DefaultPermissionPolicy, and deny all other users without the given permission. Recommended against 'allow-only'.

**So in conclusion a single rule reads:**\\
''When performing **(action)** to tickets/wikis that fits **(matching_condition)**, those users with **(permission)** will be **(result)**.''

multiple rules will run in order of (rule_name), and the last matching rule will come into effect.

'''Example 1''':
{{{#!ini
[configurable-permission-rules]
view_bug = ticket, TICKET_VIEW, type=bug, VIEW_BUG_TICKET, pass-only
}}}
This rule reads: Pass user with `VIEW_BUG_TICKET` permission for viewing tickets that matches type=bug, and deny those users without `VIEW_BUG_TICKET` permission.
This rule is equivalent to：
{{{
view_bug1 = ticket, TICKET_VIEW, type=bug, *, deny
view_bug2 = ticket, TICKET_VIEW, type=bug, VIEW_BUG_TICKET, pass
}}}
Important: the order of rules matters. Trac will auto sort the trac.ini options according to option names, so make sure your rule name implies a correct order.

'''Example 2''':
{{{#!ini
[configurable-permission-rules]
view_feature_wiki = wiki, *, Feature, VIEW_BUG_WIKI, deny
}}}
This rule reads: Deny all user with `VIEW_BUG_WIKI` permission for all actions to wiki naming feature.

'''Example 3''':
{{{#!ini
[configurable-permission-rules]
owner_edit_only11 = ticket, TICKET_MODIFY, owner=$USER, *, allow
owner_edit_only12 = ticket, TICKET_MODIFY, owner!=$USER&owner!=, *, deny
owner_edit_only13 = ticket, TICKET_MODIFY, owner=, *, pass
owner_edit_only21 = ticket, TICKET_CHGPROP, owner=$USER, *, allow
owner_edit_only22 = ticket, TICKET_CHGPROP, owner!=$USER&owner!=, *, deny
owner_edit_only23 = ticket, TICKET_CHGPROP, owner=, *, pass
}}}
This rule reads: Only the owner of the ticket can modify it.
----


== !Bugs/Feature Requests

Existing bugs and feature requests for TracConfigurablePermissionPlugin are 
[report:9?COMPONENT=TracConfigurablePermissionPlugin here].

If you have any issues, create a 
[/newticket?component=TracConfigurablePermissionPlugin new ticket].

[[TicketQuery(component=TracConfigurablePermissionPlugin&group=type,format=progress)]]

== Download

Download the zipped source from [https://github.com/trac-hacks/TracConfigurablePermissionPlugin/archive/master.zip here].

== Source

You can check out TracConfigurablePermissionPlugin from [https://github.com/trac-hacks/TracConfigurablePermissionPlugin.git here] using Git, or [https://github.com/trac-hacks/TracConfigurablePermissionPlugin browse the source].

== Installation

General instructions on installing Trac plugins can be found on the [TracPlugins#InstallingaTracplugin TracPlugins] page.

== !Author/Contributors

**Author:** [wiki:cauly] [[BR]]
**Maintainer:** [[Maintainer]] [[BR]]
**Contributors:**