diff --git a/content/en/admin/roles.md b/content/en/admin/roles.md index 283396f6..92fb7638 100644 --- a/content/en/admin/roles.md +++ b/content/en/admin/roles.md @@ -1,40 +1,84 @@ --- title: Roles -description: Roles UI, accessible from the admin dashboard +description: Roles submenu, accessible from the admin dashboard menu: docs: parent: admin --- -## Roles {#roles} +# Roles {#roles} When the database is seeded, roles are derived from the values present in [`~/config/roles.yml`](https://github.com/mastodon/mastodon/blob/main/config/roles.yml). {{< page-ref page="entities/Role" >}} The resultant roles are `Owner`, `Admin`, and `Moderator`. -A Role and its attributes can be created using the *Add role* button present on the `/admin/roles` page. +A role and its attributes can be created using the *Add role* button present on the `/admin/roles` page. ![](/assets/admin-roles-ui.png) -### Add Role {#add-role} +An existing role can be changed using the [edit role](#edit-role) feature. + +## Default roles {#default-roles} +### Base role (*Default permissions*) {#default-base-role} + +Affects all users, including users without an assigned role. + +The only permission flag that can be altered for this role is **Invite Users**. Enabling this permission will allow all users to invite other users to the server. + +The base role has a priority of `0`, and this value cannot be altered. + +### Owner {#default-owner-role} + +A role that is assigned the **Administrator** permission flag, bypassing all permissions. + +The role's *Name*, *Badge color*, and *Display badge* attributes can be changed. No permissions can be edited / revoked from this role. + +The owner role has the highest [priority](#role-priority) of any role (`1000`). The owner can modify any other role attributes. No role can be created which supersedes the owner role, as [role priority](#role-priority) for new and existing roles must be <= `999`. + +### Admin {#default-admin-role} + +A role that is assigned all **Moderation** and **Administration** permission flags. + +The **DevOps** permission flag for this role is disabled, but can be enabled by an **Owner** (or a custom role with a higher priority value). + +The role's *Name*, *Badge color*, and *Display badge* attributes can be changed. + +The admin role has a priority of `100`. + +### Moderator {#default-moderator-role} + +A role that is assigned certain **Moderation** permission flags. These include... +- **View Dashboard** +- **View Audit Log** +- **Manage Users** +- **Manage Reports** +- **Manage Taxonomies** + +The role's *Name*, *Badge color*, and *Display badge* attributes can be changed. + +The moderator role has a priority of `10`. + +## Add Role {#add-role} The `admin/roles/new` page allows for the creation of a custom Role. ![](/assets/admin-roles-new-ui.png) -**Input Fields** +### Input Fields {#add-role-input-fields} {{< page-relref ref="entities/Role#name" caption="Name">}} +Duplicate role names can exist. They are discerned in the database by their `id`, which cannot be set from the web interface. + {{< page-relref ref="entities/Role#color" caption="Badge color">}} -*Priority* +### Priority {#role-priority} - Defaults to `0` - Cannot be > `999` - - The `Owner` role by default has a value of 1000. - Can be any negative integer value +- Two roles can have the same priority value > "Higher role decides conflict resolution in certain situations. Certain actions can only be performed on roles with a lower priority." @@ -43,3 +87,12 @@ The `admin/roles/new` page allows for the creation of a custom Role. {{< page-relref ref="entities/Role#permissions" caption="Permissions">}} +## Edit role {#edit-role} + +![](/assets/admin-roles-edit-ui.png) + +An individual role can be edited by selecting *Edit* in the role list. [Input fields](#add-role-input-fields) can be changed and saved, just as they can when creating a new role. The role can also be deleted using this form. + +![](/assets/admin-roles-edit-role-ui.png) + +A logged in user with permission to **Manage Roles** will always be able to see every role, but cannot modify roles that exceed or are equal to their assigned role's [priority](#role-priority). \ No newline at end of file diff --git a/static/assets/admin-roles-edit-role-ui.png b/static/assets/admin-roles-edit-role-ui.png new file mode 100644 index 00000000..82bcb540 Binary files /dev/null and b/static/assets/admin-roles-edit-role-ui.png differ diff --git a/static/assets/admin-roles-edit-ui.png b/static/assets/admin-roles-edit-ui.png new file mode 100644 index 00000000..bc728732 Binary files /dev/null and b/static/assets/admin-roles-edit-ui.png differ