permissions.md

DO NOT LEAVE COMMENTS HERE, COMMENT ON THE RELATED ISSUE decidim/decidim#2056

Module permissions and actions

Here's a list of what permissions each module has, and what actions it is able to perform.

• Module permissions and actions
  • Definitions
  • Comparison list
    • Accountability
    • Budgets
    • Debates
    • Meetings
    • Page
    • Proposals
    • Surveys
  • Relating actions and permissions
  • Relating permissions and roles
    • Example of user roles and permissions

Definitions

Actions, in the context of this document, are what users can do, normally through the admin panel. Usually, an action will require a permission to perform that action, which can be allowed or denied based on different criteria. For example, users can edit proposals (action), but cannot edit those proposals created by a normal user (permission).

Permissions are usually based on these criteria:

• User roles, including but not limited to:
  • Organization admin
  • Participatory space admin
  • Participatory space collaborator
• Authorship of the resource the action applies to (see previous example of the proposal)

There's a Participatory space moderator user role, which can only moderate resources for a given participatory space. This role is not taken into account in this document. Admins and participatory space admins can always moderate resources. Participatory space user roles can only perform actions for the participatory space they are related to.

Actions are categorized in permissions. Each role can have multiple permissions.

Comparison list

Accountability

Permissions are checked against the Feature.

Action	Related ability	Who has permission to perform this action
Create result	manage	Admin Space admin
Read result	view	Admin Space admin
Update result	manage	Admin Space admin
Destroy result	manage	Admin Space admin
Preview result	read	Admin Space admin
Create result timeline entries	manage	Admin Space admin
Create child results	manage	Admin Space admin
Export results	manage_sensible_data	Admin Space admin
Create status	manage	Admin Space admin
Read status	read	Admin Space admin
Update status	manage	Admin Space admin
Destroy status	manage	Admin Space admin

Budgets

Permissions are checked against the Feature.

Action	Related ability	Who has permission to perform this action
Create project	manage	Admin Space admin
Read project	read	Admin Space admin
Update project	manage	Admin Space admin
Destroy project	manage	Admin Space admin
Preview project	read	Admin Space admin
Add attachment to project	manage	Admin Space admin

Debates

Action	Related ability	Who has permission to perform this action
Create debate	manage	Admin Space admin
Read debate	read	Admin Space admin Space collaborator
Update debate	manage	Admin: only if the debate is official Space admin: : only if the debate is official
Destroy debate	manage	Admin: only if the debate is official Space admin: : only if the debate is official

Meetings

Permissions are checked against the Feature.

Action	Related ability	Who has permission to perform this action
Create meeting	manage	Admin Space admin
Read meeting	read	Admin Space admin
Update meeting	manage	Admin Space admin
Destroy meeting	manage	Admin Space admin
Close meeting	manage	Admin Space admin
Add attachment to meeting	manage	Admin Space admin
Configure meeting registrations	manage	Admin Space admin
Export registrations	manage_sensible_data	Admin Space admin
Invite user to meeting	manage_sensible_data	If registrations are open: -

Page

Pages are created and destroyed together with their Feature. Permissions are checked against the Feature.

Action	Related ability	Who has permission to perform this action
Edit page	manage	Admin Space admin

Proposals

Proposals created from the admin are considered official, and a special setting needs to be activated so that official proposals can be created.

Official proposals cannot be edited.

Action	Related ability	Who has permission to perform this action
Create proposal	manage	Admin: if creation is enabled && official proposals are allowed Space admin: if creation is enabled && official proposals are allowed
Read ("preview") proposal	read	Admin Space admin
Answer proposal	collaborate	Admin: if answers are allowed for the current step or globally Space admin: if answers are allowed for the current step or globally
Export proposals	manage_sensible_data	Admin Space admin
Export comments	manage_sensible_data	Admin Space admin
Add proposal notes	collaborate	Admin Space admin

Surveys

Surveys are created and destroyed together with their Feature. Permissions are checked against the Feature.

Action	Related ability	Who has permission to perform this action
Edit survey	manage	Admin Space admin
Export user answers	manage_sensible_data	Admin Space admin

Relating actions and permissions

From these tables we can conclude that the list of actions users are able to perform, at least in the admin section, is reduced to this list:

• Read/preview a resource
• Create a resource
• Update a resource
• Create a child resource
• Destroy a resource
• Export data
• Moderate resources

There are two actions, though, that don't fall in any category of this list:

• Configure meeting registrations
• Invite a user to a meeting

We can group these actions to some categories (permissions):

Action	Permission
Read/preview a resource	view
Create a resource	manage
Update a resource	manage
Create a child resource	manage
Destroy a resource	manage
Export data	manage_sensible_data
Moderate resources	moderate
Configure meeting registrations	manage
Invite a user to a meeting	manage_sensible_data

Additionally, we're adding a collaborate permission so that some of these actions can be performed by a role between full-access admin and reader. For eaxample, Proposals uses this permission roles can answer proposals and add private notes to them.

For the public part, we'll drop the authorization system and we'll move the logic to the controller.

Relating permissions and roles

Each participatory space can define their own user roles, and for each of them apply some permissions.

Example of user roles and permissions

Role	Permissions on Space A	Permissions on Space B
Admin	read, manage, collaborate, manage_sensible_data	read, manage, collaborate, manage_sensible_data
Collaborator	read, collaborate	read

Imagine we have one instance of each participatory space, and each of them have proposals set up. In this situation, A user with the role "Collaborator" could create proposal answers and leave private notes in propsoals of the space A instance, but would ot be able to perform these actions onb propsoals of the space B instance because their would not have the rquired permissions.

There are other transversal features like file attachments that sould be included in this document. From my understanding I see the following topics:

• Files can be added, replaced, removed and deleted by the owner of the content.

• Administrators might need to be able to perform the same actions as content owners.

• Guest users and public users should be able to consume see and download the attached documents as now happens. Additionally it would be nice to be able revoke the show permission in the public side. This way it would be feasible to add private documents that are required by example to authorize the publicaton of an initiative but at the same time have no interest for the public audience.

IMHO there are multiple permissions and it's almost impossible to know what permissions we have and what we would have.

How I imagine this working is by having a list of actions defined by module and then having a panel where an admin could set a UserGroup which can do this action.

I think a similar way of what I says is something like Open Irekia does on their admin (although they don't have modules). https://alabs.gitbooks.io/doc-civictech-apps/content/apps/A2_OpenIrekia/Conclusiones.html

I'm moving the comments to the related issue, since comments in a gist do not trigger any notification:

decidim/decidim#2056

@andreslucena I think you're pointing on the right direction. In addition to your commet I would suggest that modules should be also able to propose roles composed by several permissions.

I don't have the time move to the details, but yesterday we had a meeting with Zaragoza and other city-councils that might be interested on Decidim and a relevant detail of authorization came to the surface: it would be very valuable that the result-monitoring module includes permissions to update the results independently, that is, when the result of a participatory process (or organ decision) is complex and involves different departments, the update of the execution level results needs to be done in a distributed manner so that admin priviledges are granted only for a specific Result or for a scope or category (these authorizations that are scope or category dependent are not so important if permissions can be granted per Result). Just to explain a real case scenario to take into account.

@mrcasals Regarding the manage sensible data in principle, since emails should not be accesible to admins... what kind of sensible data can be considered "sensible" to export?

Please, everyone, stop commenting this gist. Commenting here does not trigger any notification and gets lost, use the issue!