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.
The contents of this document apply to Mattermost Server version 5.0 and later.
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.
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.
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,
- Team scope if it makes sense at the team level and system level. For example,
- Channel scope if it makes sense at channel, team and system level. For example,
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 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.
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.
|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
|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.|
|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 are applied to objects that represents that user’s membership in a context. These are referenced in the
Roles field of the
ChannelMember tables, it’s the
Roles field that contains custom roles and the
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 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”).
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
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”)
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