WIP
OVERVIEW
Add three new System-scoped roles to the product: Junior Admin, User Manager and Console Viewer.
GOALS
-
-
-
SCOPE
In:
Out:
defining custom roles
plugins permissions
SPECIFICATIONS
Requirements
the goal is to add three new roles: User Manager, Console Viewer and Junior Admin (see https://www.notion.so/New-System-Roles-Special-Admins-be514029606545e3be3aa3e8c8ba507e
for current requirements). These new roles will be defined at System scope. They will have access to the System Console - like the System Adminthese new roles will possess specific rights on the following resources:
System Console sections and subsections.
config.jsonsettings (through the APIconfig.gogetandsetendpoints).various API methods that support functionalities exposed in the System Console (e.g. display analytics, link, sync groups) - separate from config settings.
High-level Architecture
Resources
System Console
The System Console has the following ten main sections (enumerated in the order they are displayed in the UX):
About
Reporting
User Management
Environment
Site Configuration
Authentication
Plugins
Integrations
Compliance
Experimental
The new roles can have the following levels of access to these sections (and in some instances to some of their subsections) - none, read, write, where:
none - the section is not displayed to the User
read - the section is displayed but all of its components are disabled, with exceptions given by the type of component (for example, web links and search boxes are not disabled) and by the permissions on the sub-sections - if the current user’s role has WRITE permissions on a subsection, it is not disabled. In some cases the page needed to access the main functionality is not disabled but the landing page components are - example: Edit Scheme is enabled, but the permission(s) tree shown in the next page is disabled.
write - the section (and its subsections) are fully accessible
Junior Admin
About - none
Reporting - read + write
User Management read+write (with the exception of not being able to reset other admin passwords)
Environment - read + write
Site Configuration - read + write
Authentication - read+write
Plugins - read+write
Integrations read+write
Compliance - none
Experimental - none
Console Viewer
About - none
Reporting - read
User Management -read
Environment - read
Site Configuration - read
Authentication - read
Plugins - read
Integrations read
Compliance - read
Experimental - read
User Manager
About - none
Reporting - none
User Management - read+write (with the exception of not being able to reset other admin passwords)
Site Configuration - none
Authentication - read
Plugins - none
Integrations - none
Compliance - none
Experimental - none
Config.json
The config.json file stores the settings that roughly map to the same System Console sections/sub-sections, but is a superset of the settings exposed in the System Console.
API methods
There are mainly two categories of API calls : get and create, patch and update. The get calls are gated by the READ permissions and the create, patch and update are gated by the WRITE permissions.
Permissions
To implement the requirements detailed above we will be define the following new permission sets:
System Console overall access permissions
Currently, 1) access to the System Console, 2) managing the settings and invoking the functionality in the System Console, 3) managing the settings in the config.json and 4) gating the API calls - all these actions are being gated using the MANAGE_SYSTEM permission assigned only to the SystemAdmin role (with some exceptions). Since we need to give access to the System Console to the new roles and we also need read-only access to the System Console, we decided to create a new set of permissions that give a more granular access to the System Console, config.json and related API methods.
READ_SETTINGS, WRITE_SETTINGS
Note: MANAGE_SYSTEM is a System/GlobalAdmin role permission only. It is used to allow the SysAdmins to perform actions that are unique to their role - for example, to set permissions on the other admins roles (by design the newly introduced admin roles cannot change the permissions of their peers, only the System Admin can).
System Console per-section/sub-section permissions
Since we need to have read-only or write access to specific sections of the System Console , we will define a new set of READ + WRITE permissions for each of the ten main sections, as well as to some of the sub-sections that some of the new roles need special access.
PERMISSION_READ_SYSCONSOLE_ABOUT PERMISSION_WRITE_SYSCONSOLE_ABOUT PERMISSION_READ_SYSCONSOLE_REPORTING PERMISSION_WRITE_SYSCONSOLE_REPORTING PERMISSION_READ_SYSCONSOLE_USERMANAGEMENT PERMISSION_WRITE_SYSCONSOLE_USERMANAGEMENT PERMISSION_READ_SYSCONSOLE_USERMANAGEMENT_USERS PERMISSION_WRITE_SYSCONSOLE_USERMANAGEMENT_USERS PERMISSION_READ_SYSCONSOLE_USERMANAGEMENT_GROUPS PERMISSION_WRITE_SYSCONSOLE_USERMANAGEMENT_GROUPS PERMISSION_READ_SYSCONSOLE_USERMANAGEMENT_TEAMS PERMISSION_WRITE_SYSCONSOLE_USERMANAGEMENT_TEAMS PERMISSION_READ_SYSCONSOLE_USERMANAGEMENT_CHANNELS PERMISSION_WRITE_SYSCONSOLE_USERMANAGEMENT_CHANNELS PERMISSION_READ_SYSCONSOLE_USERMANAGEMENT_PERMISSIONS PERMISSION_WRITE_SYSCONSOLE_USERMANAGEMENT_PERMISSIONS PERMISSION_READ_SYSCONSOLE_ENVIRONMENT PERMISSION_WRITE_SYSCONSOLE_ENVIRONMENT PERMISSION_READ_SYSCONSOLE_SITE PERMISSION_WRITE_SYSCONSOLE_SITE PERMISSION_READ_SYSCONSOLE_AUTHENTICATION PERMISSION_WRITE_SYSCONSOLE_AUTHENTICATION PERMISSION_READ_SYSCONSOLE_PLUGINS PERMISSION_WRITE_SYSCONSOLE_PLUGINS PERMISSION_READ_SYSCONSOLE_INTEGRATIONS PERMISSION_WRITE_SYSCONSOLE_INTEGRATIONS PERMISSION_READ_SYSCONSOLE_COMPLIANCE PERMISSION_WRITE_SYSCONSOLE_COMPLIANCE, PERMISSION_READ_SYSCONSOLE_EXPERIMENTAL, PERMISSION_WRITE_SYSCONSOLE_EXPERIMENTAL
There is a set of permissions that are used to gate specific tasks in the API and not covered by the MANAGE_SYSTEM permission, like PERMISSION_MANAGE_JOBS, PERMISSION_LIST_PRIVATE_TEAMS PERMISSION_JOIN_PRIVATE_TEAMS, PERMISSION_MANAGE_TEAM, etc.. These will be assigned to the new roles, depending on their specific requirements
Note that not all of them are system level permissions.
Final set of permissions
Finally, all these permission will be assigned to the existing roles and new roles as follows:
System Admin - add all the new section-specific roles (see above) to the existing set of permissions.
Console Viewer:
PERMISSION_READ_SETTINGS PERMISSION_LIST_PRIVATE_TEAMS PERMISSION_JOIN_PRIVATE_TEAMS PERMISSION_READ_SYSCONSOLE_REPORTING PERMISSION_READ_SYSCONSOLE_USERMANAGEMENT PERMISSION_READ_SYSCONSOLE_ENVIRONMENT PERMISSION_READ_SYSCONSOLE_SITE PERMISSION_READ_SYSCONSOLE_AUTHENTICATION PERMISSION_READ_SYSCONSOLE_PLUGINS PERMISSION_READ_SYSCONSOLE_INTEGRATIONS PERMISSION_READ_SYSCONSOLE_COMPLIANCE PERMISSION_READ_SYSCONSOLE_EXPERIMENTAL
Junior Admin:
PERMISSION_READ_SETTINGS PERMISSION_WRITE_SETTINGS PERMISSION_CREATE_DIRECT_CHANNEL PERMISSION_CREATE_GROUP_CHANNEL PERMISSION_CREATE_TEAM PERMISSION_CREATE_USER_ACCESS_TOKEN PERMISSION_READ_USER_ACCESS_TOKEN PERMISSION_REVOKE_USER_ACCESS_TOKEN PERMISSION_EDIT_OTHER_USERS PERMISSION_GET_PUBLIC_LINK PERMISSION_LIST_USERS_WITHOUT_TEAM PERMISSION_MANAGE_JOBS PERMISSION_MANAGE_OAUTH PERMISSION_MANAGE_ROLES PERMISSION_MANAGE_TEAM PERMISSION_LIST_PUBLIC_TEAMS PERMISSION_JOIN_PUBLIC_TEAMS PERMISSION_LIST_PRIVATE_TEAMS PERMISSION_JOIN_PRIVATE_TEAMS PERMISSION_READ_SYSCONSOLE_REPORTING PERMISSION_WRITE_SYSCONSOLE_REPORTING PERMISSION_READ_SYSCONSOLE_USERMANAGEMENT PERMISSION_WRITE_SYSCONSOLE_USERMANAGEMENT PERMISSION_READ_SYSCONSOLE_ENVIRONMENT PERMISSION_WRITE_SYSCONSOLE_ENVIRONMENT PERMISSION_READ_SYSCONSOLE_SITE PERMISSION_WRITE_SYSCONSOLE_SITE PERMISSION_READ_SYSCONSOLE_AUTHENTICATION PERMISSION_WRITE_SYSCONSOLE_AUTHENTICATION PERMISSION_READ_SYSCONSOLE_PLUGINS PERMISSION_WRITE_SYSCONSOLE_PLUGINS PERMISSION_READ_SYSCONSOLE_INTEGRATIONS PERMISSION_WRITE_SYSCONSOLE_INTEGRATIONS
User Manager:
PERMISSION_READ_SETTINGS PERMISSION_WRITE_SETTINGS PERMISSION_CREATE_USER_ACCESS_TOKEN PERMISSION_READ_USER_ACCESS_TOKEN PERMISSION_REVOKE_USER_ACCESS_TOKEN PERMISSION_EDIT_OTHER_USERS PERMISSION_GET_PUBLIC_LINK PERMISSION_LIST_USERS_WITHOUT_TEAM PERMISSION_MANAGE_JOBS PERMISSION_MANAGE_OAUTH PERMISSION_LIST_PUBLIC_TEAMS PERMISSION_LIST_PRIVATE_TEAMS PERMISSION_READ_SYSCONSOLE_USERMANAGEMENT PERMISSION_READ_SYSCONSOLE_USERMANAGEMENT_USERS PERMISSION_WRITE_SYSCONSOLE_USERMANAGEMENT_USERS PERMISSION_READ_SYSCONSOLE_USERMANAGEMENT_GROUPS PERMISSION_WRITE_SYSCONSOLE_USERMANAGEMENT_GROUPS PERMISSION_READ_SYSCONSOLE_USERMANAGEMENT_TEAMS PERMISSION_WRITE_SYSCONSOLE_USERMANAGEMENT_TEAMS PERMISSION_READ_SYSCONSOLE_USERMANAGEMENT_CHANNELS PERMISSION_WRITE_SYSCONSOLE_USERMANAGEMENT_CHANNELS PERMISSION_READ_SYSCONSOLE_USERMANAGEMENT_PERMISSIONS PERMISSION_WRITE_SYSCONSOLE_USERMANAGEMENT_PERMISSIONS PERMISSION_READ_SYSCONSOLE_AUTHENTICATION
Note: For User Manager role above, for the “User Management” section we could have had only the PERMISSION_READ_SYSCONSOLE_USERMANAGEMENT and PERMISSION_WRITE_SYSCONSOLE_USERMANAGEMENTpermissions. The reason we have more permissions, to subsections, is that in the future we project to have variants of this role that will have some of their subsections WRITE permissions removed.
Config.json mappings to permissions
Since the newly-added permissions are by definition linked to the System Console sections, we need to map them to the config.json settings. To do that, we have reviewed the existing System Console settings and mapped them to the corresponding config.json fields:
an excerpt of the sectionToPermission struct:
... sectionToPermission["TeamSettings.SiteName"] = model.PERMISSION_WRITE_SYSCONSOLE_SITE sectionToPermission["TeamSettings.CustomDescriptionText"] = model.PERMISSION_WRITE_SYSCONSOLE_SITE sectionToPermission["TeamSettings.EnableCustomBrand"] = model.PERMISSION_WRITE_SYSCONSOLE_SITE sectionToPermission["TeamSettings.CustomBrandText"] = model.PERMISSION_WRITE_SYSCONSOLE_SITE sectionToPermission["SupportSettings.HelpLink"] = model.PERMISSION_WRITE_SYSCONSOLE_SITE sectionToPermission["SupportSettings.SupportEmail"] = model.PERMISSION_WRITE_SYSCONSOLE_SITE sectionToPermission["SupportSettings.TermsOfServiceLink"] = model.PERMISSION_WRITE_SYSCONSOLE_SITE sectionToPermission["SupportSettings.PrivacyPolicyLink"] = model.PERMISSION_WRITE_SYSCONSOLE_SITE sectionToPermission["SupportSettings.AboutLink"] = model.PERMISSION_WRITE_SYSCONSOLE_SITE sectionToPermission["SupportSettings.ReportAProblemLink"] = model.PERMISSION_WRITE_SYSCONSOLE_SITE sectionToPermission["NativeAppSettings"] = model.PERMISSION_WRITE_SYSCONSOLE_SITE``` ...
Note: there are settings present in the config.json that are not settable through the System Console. These settings are not captured in the sectionToPermission table and therefore are only gated at the higher level by the READ/WRITE_SETTINGS permissions.
Resource permission computation algorithms
The goal is to maintain parity between the set of permission needed to gate a System Console section/sub-section and the equivalent set needed to gate the corresponding set of `config.json` settings + API calls.
Access to a section/subsection of the System Console
First, the user needs to be in a role that gives them access to the System Console from the chat-facing side (READ_SETTINGS). Then, depending on the role, the user could have read-only access (no WRITE_SETTINGS permission).
The rules are as follows:
if the current user's system role does not have
READorWRITEpermission on the resource, the section is hidden for the user. Example: User Manager does not havePERMISSION_READ_SYSCONSOLE_PLUGINSorPERMISSION_WRITE_SYSCONSOLE_PLUGINSso the Plugins section is hidden from view for a user in a User Manager roleif the current user's system role only has
READpermission on the resource the resource(section) is disabled. Example: User Manager hasPERMISSION_READ_SYSCONSOLE_AUTHENTICATIONso the Authentication section is disabled for a user.if the current user's system role has a
WRITEpermission on a subsection, then no matter if he hasREADorWRITEpermission on the parent section, the resulting permission on the subsection isWRITEExample: User Manager hasPERMISSION_WRITE_SYSCONSOLE_USERMANAGEMENT_USERSon the Users sub-section but alsoPERMISSION_READ_SYSCONSOLE_USERMANAGEMENTon the entire section, the resulting permission isWRITEon the sub-section.
(TBD) Note, by design we will not define a case in which a role has WRITE access on a section and READ on a subsection (the opposite can happen, see above).
Access to a setting in the config.json
Similar to the System Console, a user will need to be in a role that has the global READ_SETTINGS permission to fetch a setting and WRITE_SETTINGS to patch/update a setting. Beyond that, if the user only has READ access to a section setting, we are restricting update access to that setting. For example, since User Manager has only PERMISSION_READ_SYSCONSOLE_AUTHENTICATION, the user in this role will not be able to update the config.json fields mapped to the Authentication settings (see table above).
Access to the various API methods
Most API calls that were previously gated by the MANAGE_SYSTEM permission are now gated by the READ_* permissions for the get() calls and WRITE_* permission for the create, patch and update calls.
If we need to have more granular access to an API method that corresponds to the functionality of a sub-section in the System Console (like in the User Manager case), we will gate those calls on a case by case (a single panel functionality in the System Console panel can map to one or more API calls).
Permissions
See changes detailed above
Schema
No schema changes
REST API
The following API methods will have their gating functionality changes, as follows:
Performance
No performance degradation expected.
Plugins
CREDITS
Thanks to