Skip to content

Fix and complete the administrator roles documentation #353

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
christophdb merged 1 commit into from
Sep 2, 2026
Merged

Fix and complete the administrator roles documentation #353

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
112 changes: 97 additions & 15 deletions docs/configuration/roles-and-permissions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -116,7 +116,9 @@ If you want to modify the permissions and quotas of either or both standard role

### Custom User Roles

You can add additional user roles by extending the codeblock in `dtable_web_settings.py`.
<!-- md:flag enterprise -->

You can add additional user roles by extending the codeblock in `dtable_web_settings.py`. A custom user role inherits all permissions and quotas of the role `default`; you only need to list the values that shall differ.

To add a role `employee`, for example, add the following lines (beginning at `'employee'` and ending at `},` ) to the existing role definition.

Expand All @@ -136,30 +138,102 @@ Restart SeaTable for the new role to become available in SeaTable.

Similar to a user role, an administrator role is comprised of several permissions, but no quotas.

!!! warning "Administrator permissions default to False"

User roles and administrator roles behave in opposite ways when a permission is not set: a user role grants everything that is not explicitly listed, an administrator role grants **nothing** that is not explicitly listed. Internally, every administrator role is merged onto a hidden role `dummy_admin` in which all permissions are set to `False`. Consequently, you must list every single permission that an administrator role shall have.

### Administrator Permissions

The following permissions are supported in administrator roles:

| Permission | Added in version | Permission to ... | Additional information |
| ------------------------ | ---------------- | --------------------------------------------------------------------------------------------- | ---------------------- |
| can_view_system_info | 1.0 | See/access "Info" menu in System admin | |
| can_view_statistic | 1.0 | See/access "Statistic" menu in System admin | |
| can_config_system | 1.0 | See/access "Settings" menu in System admin | |
| can_manage_user | 1.0 | See/access "Users" menu in System admin | |
| can_manage_group | 1.0 | See/access "Groups" menu in System admin | |
| can_manage_external_link | 1.0 | See/access "External links" menu in System admin | |
| can_view_admin_log | 1.0 | See/access "Admin logs" menu in System admin | |
| can_manage_user_log | 1.0 | See/access the tab "Login logs" in "Audit logs" menu in System admin | |
| can_manage_audit_log | 1.0 | See/access the tabs "Action logs" and "File access logs" in "Audit logs" menu in System admin | |
| can_manage_organization | 1.0 | See/access "Organizations" menu in System admin | |

| Permission | Added in version | Permission to ... | Additional information |
| --------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| can_view_system_info | 1.0 | See/access "Info" menu in System admin | The license cannot be uploaded with this permission alone. |
| can_view_statistic | 1.0 | See/access "Statistic" menu in System admin | |
| can_config_system | 1.0 | See/access "Settings" menu in System admin | |
| can_manage_user | 1.0 | See/access "Users" menu in System admin | |
| can_update_user | 1.6 | See and modify the details of an individual user | Grants access to a single user account without granting the complete "Users" menu. An administrator with `can_manage_user` has these rights as well. |
| can_manage_group | 1.0 | See/access "Groups" menu in System admin | |
| can_manage_external_link | 1.0 | See/access "External links" menu in System admin | |
| can_view_audit_log | 5.1 | See/access "Audit logs" menu in System admin and its tabs "Action logs", "File access logs" and "Permission logs" | This permission controls the menu itself. Without it, the menu is hidden — even if `can_view_user_log` is set. The tabs besides "Login logs" additionally require the *user* permission `can_use_advanced_permissions`. |
| can_view_user_log | 1.0 | See/access the tabs "Login logs" and "Group member logs" in "Audit logs" menu in System admin | Requires `can_view_audit_log` to make the menu visible. |
| can_view_admin_log | 1.0 | See/access "Admin logs" menu in System admin | |
| can_manage_organization | 2.0 | See/access "Organizations" menu in System admin | The menu is only shown if multi-tenancy is enabled. |
| can_update_organization | 2.2 | See and modify the details of an individual organization | Grants access to a single organization without granting the complete "Organizations" menu. An administrator with `can_manage_organization` has these rights as well. |
| can_manage_app | 5.3 | See/access "Apps" menu in System admin | |
| other_permission | 5.2 | See/access "Virus scan" menu in System admin | Despite its generic name, this permission currently only controls the virus scan records. |
| can_manage_library | 1.0 | Administer libraries via the API | Inherited from Seafile. SeaTable's system administration has no "Libraries" menu, so this permission only guards the corresponding API endpoints. |
| can_manage_base | 2.0 | Administer bases via the API | The "Bases" menu is shown to the role `default_admin` only and cannot be granted to another role. This permission only guards the corresponding API endpoints. |
| can_manage_form | 2.0 | Administer forms via the API | The "Forms" menu is shown to the role `default_admin` only and cannot be granted to another role. This permission only guards the corresponding API endpoints. |
| can_manage_sys_notification | 2.0 | Administer system notifications via the API | The "Notifications" menu is shown to the role `default_admin` only and cannot be granted to another role. This permission only guards the corresponding API endpoints. |
| can_manage_plugin | 2.0 | Administer plugins via the API | The "Plugins" menu is shown to the role `default_admin` only and cannot be granted to another role. This permission only guards the corresponding API endpoints. |

The default value for all permissions is False. This means that if a permission is not specifically set, the role does **not** grant the permission.

### Standard Administrator Roles

SeaTable has four standard, preconfigured administrator roles `default admin`, `audit admin`, `daily admin` and `custom admin`. They can be used in the Users' section of the system administration without prior configuration.
SeaTable has four standard, preconfigured administrator roles `default_admin`, `system_admin`, `daily_admin` and `audit_admin`. They can be used in the Users' section of the system administration without prior configuration.

Only an administrator with the role `default_admin` can assign an administrator role to another administrator. All other administrator roles can see the role of an administrator, but not change it.

The standard administrator roles are defined as follows:

```python
ENABLED_ADMIN_ROLE_PERMISSIONS = {
# can do everything
'default_admin': {
'can_view_system_info': True,
'can_view_statistic': True,
'can_config_system': True,
'can_manage_library': True,
'can_manage_user': True,
'can_update_user': True,
'can_manage_group': True,
'can_manage_external_link': True,
'can_view_user_log': True,
'can_view_audit_log': True,
'can_view_admin_log': True,
'can_manage_base': True,
'can_manage_app': True,
'can_manage_form': True,
'can_manage_organization': True,
'can_update_organization': True,
'can_manage_sys_notification': True,
'can_manage_plugin': True,
'other_permission': True,
},
# can ONLY access the "Info" and "Settings" menu
'system_admin': {
'can_view_system_info': True,
'can_config_system': True,
},
# can ONLY access the "Info", "Statistic", "Users", "Groups" and "Audit logs" menu
'daily_admin': {
'can_view_system_info': True,
'can_view_statistic': True,
'can_manage_library': True,
'can_manage_user': True,
'can_update_user': True,
'can_manage_group': True,
'can_view_user_log': True,
'can_view_audit_log': True,
},
# can ONLY access the "Info", "Audit logs" and "Admin logs" menu
'audit_admin': {
'can_view_system_info': True,
'can_view_admin_log': True,
'can_view_user_log': True,
'can_view_audit_log': True,
}
}
```

If you want to modify the permissions of one or more standard administrator roles, copy-and-paste the above codeblock into `dtable_web_settings.py` and modify as per your needs. Restart SeaTable for the changes to take effect.

### Custom Administrator Roles

<!-- md:flag enterprise -->

Just like a user role, you can add additional administrator roles by adding/modifying the following codeblock in `dtable_web_settings.py`.

```python
Expand All @@ -173,3 +247,11 @@ ENABLED_ADMIN_ROLE_PERMISSIONS = {
}
}
```

Restart SeaTable for the new role to become available in SeaTable.

!!! info "Custom roles are displayed with their technical name"

The four standard administrator roles (and the two standard user roles) have a translated display name in the web interface: `default_admin` is shown as "Default admin", `system_admin` as "System admin", `daily_admin` as "Daily admin" and `audit_admin` as "Audit admin".

For every other role, SeaTable falls back to the key you defined. A role `new_admin_role` therefore appears as `new_admin_role` in the role dropdown of the Users' section — underscores included. If you want a nice-looking entry, choose the key accordingly, e.g. `Support` instead of `support_admin_role`.
Loading