Groups-to-Roles Technical Specification

Owned by Dennis Kittrell (Deactivated)
Jan 13, 2020
4 min read

Dec 2, 2019

OVERVIEW

This feature allows for team and channel membership roles to be synchronized with groups. This could be used, for example, to…

  • Make Managers group members have the Team Admin role on the Staff team.

  • Make all Developers team members have the Channel Admin role on the Contributors channel.

  • Remove the Team Admin role on the Staff team from anyone who is not in the Managers group.

  • Add all new Staff team members with the Team Member role.

GOALS

  1. Outline the architectural proposal

  2. Ensure that there is agreement and no surprises about how it will be determined what role a user has when being added to a team/channel

  3. Ensure that there is agreement and no surprises about how the background sync process may update team/channel member roles

  4. Ensure that the performance risks are conveyed

SCOPE

In scope:

The architectural changes required for an MVP of this feature to operate based on the UX screenshots included. 

Not in scope:

  • Creating a new background sync job separate from the LDAP sync job (and any UX related to that).

  • Custom roles.

  • Syncing guest roles via groups (this will continue to be done using LDAP filters for now).

  • Updating the CLI so that group configuration and administration via the CLI is possible (it currently is not without groups-to-roles).

BACKGROUND READING

From the InVision prototype named “Final Spec - LDAP Group Sync”, the below five screenshots contain the UX related to this feature (the “members” widget on a team/channel notwithstanding). 

The UX consists of a new drop-down in five existing views in Mattermost:

  1. The system console > group configuration details view > team and channel membership list.



  1. The system console > channel configuration details view > synced groups list.



  1. The system console > team configuration details view > synced groups list.



  1. The chat-facing team groups list view.



  1. The chat-facing channel groups list view.



SPECIFICATIONS

High-level Architecture

Prior to a user being added to any team/channel, a check will be performed to determine what role to use for the user. Namely as a Guest, as a Team/Channel User, or as a Team/Channel Admin.

Also, a background job will execute at a regular interval to update the roles of team/channel members of group-synced teams/channels. A user may be changed from a team/channel admin to a team/channel user or vice versa.

At a high level the logic is as follows:

The update/add step of the diagram depends on whether the user is being added to the team/channel anew (add) or whether the check is being approached from a background sync process (update).

It is important to note that existing team/channel members of non-group-synced teams/channels will not have their roles updated upon sync.

Schema

A new boolean column named SchemeAdmin will be added to each of the existing GroupTeams and GroupChannels tables. The default value will be false.

The argument could be made to add SchemeUser and SchemeGuest boolean columns (in addition the new SchemeAdmin column) for symmetry with other tables. Those columns will not be added yet because the data would not be currently used because guests are not configurable at the team/channel scope. Guests are always—in the current UX—at the system scope and other code changes would be required to change this. Additional columns can be added if/when the feature is developed to make guests available at the team/channel scope.

REST API

The following API endpoints will be affected by the new field added to the GroupSyncable model:

  1. PUT /api/v4/groups/:group_id/teams/:team_id/patch

  2. PUT /api/v4/groups/:group_id/channels/:channel_id/patch

  3. POST /api/v4/groups/:group_id/teams/:channel_id/link

  4. POST /api/v4/groups/:group_id/channels/:channel_id/link

  5. GET /api/v4/groups/:group_id/teams/:team_id

  6. GET /api/v4/groups/:group_id/channels/:channel_id

  7. GET /api/v4/groups/:group_id/teams

  8. GET /api/v4/groups/:group_id/channels

Endpoints 1 and 2 will be used when toggling the dropdowns as shown in the mocks.

Background jobs

A new step will be added to the existing LDAP sync job. This step must iterate through each group-synced team/channel to see whether any of the team/channel members with the Team/Channel Admin role must be changed to Team/Channel Member (or vice versa). In the future when the UX allows non-LDAP groups then this step will be moved into its own background job independent of the LDAP sync job.

CLI

Changes not in scope.

Configuration

No config changes.

Frontend

New dropdowns in five existing views as outlined above and as seen in the InVision mocks.

Performance

Adding a user to a team/channel: This feature will slow down the process of adding a user to a team/channel because at least one new DB query must be performed to know the role to add the user with. Guests and system admins will not require the DB check.

Bulk import: The performance decrease of adding a user to a team/channel will apply and be multiplied across each team/channel addition done by the import.

LDAP sync job: The LDAP sync job will be slower because each group-synced team/channel must be checked to see whether the member roles need updating.

Plugins

No changes.

CREDITS

Thanks to George for listening to and validating the proposed DB changes and high-level behaviour of syncing.

Thanks to Scott, Catalin, Dennis, Hossein and Mike for helping to validate that a SchemeGuest column was not needed because guests are currently system-wide in the UX, rather than configurable at the team/channel scope.

Thanks to whomever made this pretty template.