Advanced Permissions: Backend Infrastructure

This document outlines the backend server infrastructure for permissions in Mattermost and is recommended only for technical Admins or developers looking to make modifications to their installation.

Note

The contents of this document apply to Mattermost Server version 5.0 and later.

Entity Definitions

Permissions

A permission describes a permitted action which may be carried out on an object. It describes the action that users may perform in the context in which they have been assigned the role granting the permission.

Roles

A role is something to which permissions are granted, that is then assigned to users in contexts in order to grant them the assigned permissions in that context. One user may end up with different sets of permissions granted by different roles in different contexts.

Scope

Permissions live within a given scope. There are three scopes in the Mattermost system: System, Team and Channel. Permissions cascade down the scopes from the context in which they are applied. For example, if a “Channel” scoped permission is applied to a “Team” context, the permission applies to any channels within that team. A permission is considered,

• System scope if it makes sense only on the system level. For example, manage_oauth.
• Team scope if it makes sense at the team level and system level. For example, create_public_channel.
• Channel scope if it makes sense at channel, team and system level. For example, manage_public_channel_properties.

Context

A context is an instance of a scope. For example, a channel called “Developers Hangout” is an instance of channel scope. Contexts have hierarchical relationships between them that reflect the hierarchical ordering of scopes. Each context has one parent, and may have multiple children, with the ultimate parent context being the system context:

• A channel context has a parent team context, whose parent is the system context. For example, the “Developers Hangout” channel is the channel context, with parent team context “Contributors Team”, with parent system context.
• A team context has a parent system context and child channel contexts. For example, the “Contributors Team” is the team context, with parent system context, and with children channel contexts such as “Developers Hangout”, “Reception” and “Marketing”.

When determining whether a user is allowed to carry out a given action in a given context, the union of the permissions of all roles that user has been assigned in the current context and its parent contexts is calculated. This enables permissions to cascade down the scope hierarchy. For example, if a users is granted the manage_public_channel_properties permission in a role in the system context, then the user has permissions to manage public channel properties in all channels, in all teams, of which they are a member.

Schemes

Schemes describe the default roles applied to users in a context, and all child contexts. Schemes are either defined specifically for a context, or if they are not specified, the relevant parts of the parent context’s scheme are applied, ultimately climbing the hierarchy to the System Scheme, which serves the purpose of providing the system-wide defaults. For example, if Team A does not have a team-scoped scheme defined, the System Scheme will provide the defaults for all contexts in Team A.

Additionally, the lowest-scoped scheme always takes precedence in the context. For example, if Team B has a team-scoped scheme, that scheme takes precedence over the System Scheme defaults for all contexts in Team B.

Data Structure

Permissions

Permissions in Mattermost are a property of the server code base and are not created or modified dynamically. The current set of permissions are as described in the table below.

Mattermost Permissions

Name (i18n)	Scope	Description
invite_user	team	Invite users to the team using Send Email Invite or Get Team Invite Link.
add_user_to_team	team	Add existing server users to the current team.
use_slash_commands	channel	Use slash commands.
manage_slash_commands	system	Create, edit and delete your own slash commands.
manage_others_slash_commands	system	Edit or delete other users slash commands.
create_public_channel	team	Create public channels.
create_private_channel	team	Create private channels.
manage_public_channel_members	channel	Manage public channel members.
manage_private_channel_members	channel	Manage private channel members.
assign_system_admin_role	system	Grant other users System Admin role.
manage_roles	system	Manage other users system-wide roles.
manage_team_roles	team	Add and remove team members.
manage_channel_roles	channel	Add and remove channel members.
manage_system	system	Access to System Console.
create_direct_channel	system	Open direct message channels.
create_group_channel	system	Open group message channels.
manage_public_channel_properties	channel	Edit public channel name, header and purpose.
manage_private_channel_properties	channel	Edit private channel name, header and purpose.
list_team_channels	team	List public channels in a team.
join_public_channels	team	Join public channels.
delete_public_channel	channel	Archive public channels.
delete_private_channel	channel	Archive private channels.
edit_other_users	system	Edit values on the user object of other users.
read_channel	channel	View posts in a channel.
add_reaction	channel	Add emoji reactions to posts.
remove_reaction	channel	Remove emoji reactions from posts.
remove_others_reactions	channel	Remove other users emoji reactions from posts.
permanent_delete_user	system	Permanently delete other users.
upload_file	system	Upload file attachements to posts.
manage_incoming_webhooks	team	Create, edit and delete your own incoming webhooks.
manage_outgoing_webhooks	team	Create, edit and delete your own outgoing webhooks.
manage_others_webhooks	team	Edit and delete other users incoming or outgoing webhooks.
manage_oauth	system	Create, edit and delete your own OAuth 2.0 apps.
manage_system_wide_oauth	system	Edit or delete other users’ OAuth 2.0 apps.
create_post	channel	Post in channels.
edit_post	channel	Authors edit their own posts. Edit post time limit is controlled by the "PostEditTimeLimit" config.
edit_others_posts	channel	Edit other users posts.
delete_post	channel	Authors delete their own posts.
delete_others_posts	channel	Delete other users’ posts.
remove_user_from_team	team	Remove users from team.
create_team	system	Create teams.
manage_team	team	Access Team Settings.
import_team	system	Import teams in Team Settings.
view_team	team	Read the Team Object
list_users_without_team	system	List users without a team.
create_user_access_token	system	Create user access tokens.
read_user_access_token	system	Read user access tokens by ID.
revoke_user_access_token	system	Revoke user access tokens.
manage_jobs	system	Create and cancel jobs.
create_emojis	system	Create custom emoji.
delete_emojis	system	Delete own custom emoji.
delete_others_emojis	system	Delete custom emoji created by others.

Roles Field

Roles are applied to objects that represents that user’s membership in a context. These are referenced in the Roles field of the User, TeamMember, ChannelMember and Schemes Tables.

In the TeamMember and ChannelMember tables, it’s the Roles field that contains custom roles and the SchemeAdmin and SchemeUser booleans that indicate the member object should inherit the respective roles from the relevant scheme, either the default or custom scheme assigned to the relevant team.

Roles Table

Roles are dynamic and user configurable, necessitating a database table with the following fields:

• Id (Autoincrement, Primary Key)
• Name (Unique String with Character Constraints, e.g. “team_user”).
• Display Name (String)
• Description (String)
• Permissions (String): Space-separated permissions names
• Scheme Managed (bool): Indicates whether this role is managed as part of a scheme.
• BuiltIn (bool): Indicates if this role is built in to the Mattermost system and not removable by the user.

The System Scheme is built in to the product and it’s roles are defined as BuiltIn: true in the Roles table.

Schemes Table

Schemes are dynamic and user configurable, necessitating a database table with the following fields:

• Id (Autoincrement, Primary Key)
• Name (Unique String with Character Constraints, e.g. “corporate_scheme”)
• Display Name
• Description (String)
• Scope (String): Team or Channel
• Team Admin Role (String): Empty if Channel Scope
• Team User Role (String): Empty if Channel Scope
• Channel Admin Role (String): Always provided
• Channel User Role (String): Always provided