Clarify system roles

mattermost · Feb 6, 2025 · 3f706a2 · 3f706a2
1 parent e9538d5
commit 3f706a2
Showing 1 changed file with 39 additions and 16 deletions.
diff --git a/source/onboard/delegated-granular-administration.rst b/source/onboard/delegated-granular-administration.rst
@@ -15,34 +15,57 @@ These admin roles permit granular access to specific areas of the System Console
 Available roles
 ----------------
 
-A system admin can set up the following delegated granular administration in the System Console:
-
-- **System Manager:** This role has read/write permissions for management areas, such as user management and integrations, but not user permissions. This role has read only access to authentication, reporting, and licensing.
-- **User Manager:** This role is able to read/write to all the user management areas, but not user permissions, and read-only access to authentication.
-- **Custom Group Manager** This role has permissions to :doc:`create, edit, restore, and delete custom user groups </collaborate/organize-using-custom-user-groups>`. This role can be used to assign individual users the ability to manage custom groups when **Custom Groups** permissions are removed for **All Members** via **System Console > Permissions > Edit Scheme > Custom Groups**.
-- **Viewer:** The Viewer role can view all areas of the System Console, but has no write access.
-
-When a user is assigned a system role, they have role-based access to the System Console and the API endpoints. Each role has a different set of default permissions, and what users can access or view depends on the role they've been assigned.
+A system admin can configure the following delegated granular administration
+roles in the System Console. Each role has a set of default permissions, which
+can be adjusted as needed.
+
+- **System Manager:** This role can be configured to have read/write
+permissions in different management areas
+- **User Manager:** This role can be condigured to have read/write to all the
+user management areas and to authentication
+- **Custom Group Manager** This role has permissions to :doc:`create, edit,
+restore, and delete custom user groups
+</collaborate/organize-using-custom-user-groups>`. This role can be used to
+assign individual users the ability to manage custom groups when **Custom
+Groups** permissions are removed for **All Members** via **System Console >
+Permissions > Edit Scheme > Custom Groups**.
+- **Viewer:** The Viewer role can view all areas of the System Console, and can
+be configured with write access where needed.
+
+When a user is assigned a system role, they have role-based access to the
+System Console and the underlying API endpoints. Each role has a different set
+of default permissions, and what users can access or view depends on the role
+they've been assigned.
+
+The table below lists the default permissions for each role.
 
 +----------------------+-----------------------+---------------------------------------+
 | **System role**      | **Read/Write access** | **Read Only access**                  |
 +----------------------+-----------------------+---------------------------------------+
-| System Manager       | - User Management     | - (User Management) Permissions       |
-|                      | - Environment         | - Edition/License                     |
-|                      | - Site Configuration  | - Reporting                           |
-|                      | - Integrations        | - Authentication                      |
-|                      |                       | - Plugins                             |
+| System Manager       | - User Management     | - Edition/License                     |
+|                      |   - Groups            | - Reporting                           |
+|                      |   - Teams             | - Authentication                      |
+|                      |   - Channels          | - Plugins                             |
+|                      |   - Permissions       |                                       |
+|                      | - Environment         |                                       |
+|                      | - Site Configuration  |                                       |
+|                      | - Integrations        |                                       |
 +----------------------+-----------------------+---------------------------------------+
 | User Manager         | - User Management     | - (User Management) Permissions       |
-|                      | - Groups              | - Authentication                      |
-|                      | - Teams               |                                       |
-|                      | - Channels            |                                       |
+|                      |   - Groups            | - Authentication                      |
+|                      |   - Teams             |                                       |
+|                      |   - Channels          |                                       |
 +----------------------+-----------------------+---------------------------------------+
 | Custom Group Manager | Custom User Groups    | N/A                                   |
 +----------------------+-----------------------+---------------------------------------+
 | Viewer               | N/A                   | - All pages within the System Console |
 +----------------------+-----------------------+---------------------------------------+
 
+Admins should carefully review and configure these settings to align with their
+organization's needs. Particular caution should be exercised with Permissions
+write access, as it enables modifications to the permissions of any role,
+except for the delegated granular administrator roles.
+
 Assign admin roles
 -------------------