docs: custom root roles (#4451)

https://linear.app/unleash/issue/2-1136/custom-root-roles-documentation

- [Adds documentation referencing custom root
roles](https://unleash-docs-git-docs-custom-root-roles-unleash-team.vercel.app/reference/rbac);
- [Adds a "How to create and assign custom root roles" how-to
guide](https://unleash-docs-git-docs-custom-root-roles-unleash-team.vercel.app/how-to/how-to-create-and-assign-custom-root-roles);
 - Standardizes "global" roles to "root" roles;
- Standardizes "standard" roles to "predefined" roles to better reflect
their behavior and what is shown in our UI;
 - Updates predefined role descriptions and makes them consistent;
 - Updates the side panel description of the user form;
- Includes some boy scouting with some tiny fixes of things identified
along the way (e.g. the role form was persisting old data when closed
and re-opened);
 
 Questions:

- Is it worth expanding the "Assigning custom root roles" section in the
"How to create and assign custom root roles" guide to include the steps
for assigning a root role for each entity (user, service account,
group)?
- Should this PR include an update to the existing "How to create and
assign custom project roles" guide? We've since updated the UI;

---------

Co-authored-by: Thomas Heartman <[email protected]>

frontend/src/component/admin/roles/RoleForm/useRoleForm.ts

@@ -68,6 +68,14 @@ export const useRoleForm = (
         setErrors(errors => ({ ...errors, [field]: error }));
     };
 
+    const reload = () => {
+        setName(initialName);
+        setDescription(initialDescription);
+        setCheckedPermissions(
+            permissionsToCheckedPermissions(initialPermissions)
+        );
+    };
+
     return {
         name,
         description,
@@ -83,5 +91,6 @@ export const useRoleForm = (
         isNotEmpty,
         hasPermissions,
         ErrorField,
+        reload,
     };
 };

frontend/src/component/admin/roles/RoleModal/RoleModal.tsx

@@ -7,7 +7,7 @@ import { RoleForm } from '../RoleForm/RoleForm';
 import { useRoles } from 'hooks/api/getters/useRoles/useRoles';
 import useToast from 'hooks/useToast';
 import { formatUnknownError } from 'utils/formatUnknownError';
-import { FormEvent } from 'react';
+import { FormEvent, useEffect } from 'react';
 import { useRolesApi } from 'hooks/api/actions/useRolesApi/useRolesApi';
 import { useRole } from 'hooks/api/getters/useRole/useRole';
 import { PredefinedRoleType } from 'interfaces/role';
@@ -60,6 +60,7 @@ export const RoleModal = ({
         setError,
         clearError,
         ErrorField,
+        reload: reloadForm,
     } = useRoleForm(role?.name, role?.description, role?.permissions);
     const { refetch: refetchRoles } = useRoles();
     const { addRole, updateRole, loading } = useRolesApi();
@@ -119,6 +120,10 @@ export const RoleModal = ({
         }
     };
 
+    useEffect(() => {
+        reloadForm();
+    }, [open]);
+
     const titleCasedType = type[0].toUpperCase() + type.slice(1);
 
     return (
@@ -134,7 +139,11 @@ export const RoleModal = ({
                 modal
                 title={editing ? `Edit ${type} role` : `New ${type} role`}
                 description={`${titleCasedType} roles allow you to control access to ${type} resources. Besides the built-in ${type} roles, you can create and manage custom ${type} roles to fit your needs.`}
-                documentationLink="https://docs.getunleash.io/reference/rbac"
+                documentationLink={`https://docs.getunleash.io/reference/rbac${
+                    type === ROOT_ROLE_TYPE
+                        ? '#custom-root-roles'
+                        : '#custom-project-roles'
+                }`}
                 documentationLinkLabel="Roles documentation"
                 formatApiCode={formatApiCode}
             >

frontend/src/component/admin/users/CreateUser/CreateUser.tsx

@@ -81,9 +81,8 @@ const CreateUser = () => {
         <FormTemplate
             loading={loading}
             title="Create Unleash user"
-            description="In order to get access to Unleash needs to have an Unleash root role as Admin, Editor or Viewer.
-            You can also add the user to projects as member or owner in the specific projects."
-            documentationLink="https://docs.getunleash.io/reference/rbac#standard-roles"
+            description="In order for a user to get access to Unleash, they need to be assigned a root role, such as Viewer, Editor, or Admin."
+            documentationLink="https://docs.getunleash.io/reference/rbac#predefined-roles"
             documentationLinkLabel="User management documentation"
             formatApiCode={formatApiCode}
         >

frontend/src/component/admin/users/EditUser/EditUser.tsx

@@ -77,9 +77,8 @@ const EditUser = () => {
         <FormTemplate
             loading={loading}
             title="Edit user"
-            description="In order to get access to Unleash needs to have an Unleash root role as Admin, Editor or Viewer.
-            You can also add the user to projects as member or owner in the specific projects."
-            documentationLink="https://docs.getunleash.io/reference/rbac#standard-roles"
+            description="In order for a user to get access to Unleash, they need to be assigned a root role, such as Viewer, Editor, or Admin."
+            documentationLink="https://docs.getunleash.io/reference/rbac#predefined-roles"
             documentationLinkLabel="User management documentation"
             formatApiCode={formatApiCode}
         >

src/lib/openapi/spec/create-user-response-schema.ts

@@ -11,7 +11,7 @@ export const createUserResponseSchema = {
         ...userSchema.properties,
         rootRole: {
             description:
-                'Which [root role](https://docs.getunleash.io/reference/rbac#standard-roles) this user is assigned. Usually a numeric role ID, but can be a string when returning newly created user with an explicit string role.',
+                'Which [root role](https://docs.getunleash.io/reference/rbac#predefined-roles) this user is assigned. Usually a numeric role ID, but can be a string when returning newly created user with an explicit string role.',
             oneOf: [
                 {
                     type: 'integer',

src/lib/openapi/spec/user-schema.ts

@@ -61,7 +61,7 @@ export const userSchema = {
         },
         rootRole: {
             description:
-                'Which [root role](https://docs.getunleash.io/reference/rbac#standard-roles) this user is assigned',
+                'Which [root role](https://docs.getunleash.io/reference/rbac#predefined-roles) this user is assigned',
             type: 'integer',
             example: 1,
             minimum: 0,

src/lib/openapi/spec/users-schema.ts

@@ -19,7 +19,7 @@ export const usersSchema = {
         rootRoles: {
             type: 'array',
             description:
-                'A list of [root roles](https://docs.getunleash.io/reference/rbac#standard-roles) in the Unleash instance.',
+                'A list of [root roles](https://docs.getunleash.io/reference/rbac#predefined-roles) in the Unleash instance.',
             items: {
                 $ref: '#/components/schemas/roleSchema',
             },

src/lib/routes/admin-api/user-admin.ts

@@ -187,7 +187,7 @@ export default class UserAdminController extends Controller {
                     tags: ['Users'],
                     operationId: 'getUsers',
                     summary:
-                        'Get all users and [root roles](https://docs.getunleash.io/reference/rbac#standard-roles)',
+                        'Get all users and [root roles](https://docs.getunleash.io/reference/rbac#predefined-roles)',
                     description:
                         'Will return all users and all available root roles for the Unleash instance.',
                     responses: {

src/migrations/20230808104232-update-root-roles-descriptions.js

@@ -0,0 +1,20 @@
+exports.up = function (db, cb) {
+    db.runSql(
+        `
+        UPDATE roles SET description = 'Users with the root admin role have superuser access to Unleash and can perform any operation within the Unleash platform.' WHERE name = 'Admin';
+        UPDATE roles SET description = 'Users with the root editor role have access to most features in Unleash, but can not manage users and roles in the root scope. Editors will be added as project owners when creating projects and get superuser rights within the context of these projects. Users with the editor role will also get access to most permissions on the default project by default.' WHERE name = 'Editor';
+        UPDATE roles SET description = 'Users with the root viewer role can only read root resources in Unleash. Viewers can be added to specific projects as project members. Users with the viewer role may not view API tokens.' WHERE name = 'Viewer';
+        UPDATE roles SET description = 'Users with the project owner role have full control over the project, and can add and manage other users within the project context, manage feature toggles within the project, and control advanced project features like archiving and deleting the project.' WHERE name = 'Owner';
+        UPDATE roles SET description = 'Users with the project member role are allowed to view, create, and update feature toggles within a project, but have limited permissions in regards to managing the project''s user access and can not archive or delete the project.' WHERE name = 'Member';
+        `,
+        cb,
+    );
+};
+
+exports.down = function (db, cb) {
+    db.runSql(
+        `
+        `,
+        cb,
+    );
+};

website/docs/how-to/how-to-add-sso-azure-saml.md

@@ -92,7 +92,7 @@ Use the values from the [previous section](#azure-details) to fill out the form:
 2. In the single sign-on URL field, add the **login URL**. It should look something like `https://login.microsoftonline.com/**[identifier]**/saml2`
 3. In the X.509 certificate field, add the content of the `X509Certificate` tag from the **federation metadata XML**.
 
-Optionally, you may also choose to “Auto-create users”. This will make Unleash automatically create new users on the fly the first time they sign-in to Unleash with the given SSO provider (JIT). If you decide to automatically create users in Unleash you must also provide a list of valid email domains separated by commas. You must also decide which global Unleash role they will be assigned. Without this enabled you will need to manually add users to Unleash before SSO will work for their accounts and Unleash.
+Optionally, you may also choose to “Auto-create users”. This will make Unleash automatically create new users on the fly the first time they sign-in to Unleash with the given SSO provider (JIT). If you decide to automatically create users in Unleash you must also provide a list of valid email domains separated by commas. You must also decide which root Unleash role they will be assigned. Without this enabled you will need to manually add users to Unleash before SSO will work for their accounts and Unleash.
 
 ![Unleash: SAML 2.0 filled out with entity ID, Single Sign-On URL, and X.509 certificate and auto-creating users for users with the '@getunleash.ai' and '@getunleash.io' emaiil domains.](/img/sso-azure-saml-unleash-config.png)
 
@@ -127,4 +127,4 @@ Add the same "Name" you used from the previous section (eg. "groups") as the "Gr
 
 **Note that Azure only supports sending up to 150 groups.** If you have more groups than this, you can setup a filter in Azure to only send the relevant groups to Unleash.
 
-![Unleash: SAML 2.0 setup, filtering groups by name ](/img/sso-azure-saml-group-filtering.png)
+![Unleash: SAML 2.0 setup, filtering groups by name ](/img/sso-azure-saml-group-filtering.png)

website/docs/how-to/how-to-add-sso-open-id-connect.md

@@ -63,7 +63,7 @@ Navigate to Unleash and insert the details (Discover URL, Client Id and Client S
 
 > Pleas note that the `Discover URL` must be a valid URL and must include the `https://` prefix. For example: **https://dev-example-okta.com** is a valid discovery URL.
 
-You may also choose to “Auto-create users”. This will make Unleash automatically create new users on the fly the first time they sign-in to Unleash with the given SSO provider (JIT). If you decide to automatically create users in Unleash you must also provide a list of valid email domains. You must also decide which global Unleash role they will be assigned (Editor role will be the default).
+You may also choose to “Auto-create users”. This will make Unleash automatically create new users on the fly the first time they sign-in to Unleash with the given SSO provider (JIT). If you decide to automatically create users in Unleash you must also provide a list of valid email domains. You must also decide which root Unleash role they will be assigned (Editor role will be the default).
 
 ![Unleash: Configure OpenID Connect](/img/sso-oidc-unleash.png)
 

website/docs/how-to/how-to-add-sso-saml.md

@@ -66,7 +66,7 @@ Click the “View Setup Instructions” to get the necessary configuration requi
 
 Go back to Unleash Admin Dashboard and navigate to `Admin Menu -> Single-Sign-On -> SAML`. Fill in the values captured in the _"Get the Okta Setup Instructions"_ step.
 
-You may also choose to “Auto-create users”. This will make Unleash automatically create new users on the fly the first time they sign-in to Unleash with the given SSO provider (JIT). If you decide to automatically create users in Unleash you must also provide a list of valid email domains. You must also decide which global Unleash role they will be assigned (Editor role will be the default).
+You may also choose to “Auto-create users”. This will make Unleash automatically create new users on the fly the first time they sign-in to Unleash with the given SSO provider (JIT). If you decide to automatically create users in Unleash you must also provide a list of valid email domains. You must also decide which root Unleash role they will be assigned (Editor role will be the default).
 
 ![Unleash: SAML 2.0](/img/sso-saml-unleash.png)
 

website/docs/how-to/how-to-add-users-to-unleash.md

@@ -13,7 +13,7 @@ You can add new users to Unleash in `Admin > Users`.
 2. To add a new user to your Unleash instance, use the "new user" button:
     ![The Unleash users page with the 'add new user' button being pointed to.](/img/user_admin-add-user.jpg)
 
-3. Fill out the required fields in the "create user" form. Refer to the [global roles overview](../reference/rbac.md#standard-roles) for more information on roles.
+3. Fill out the required fields in the "create user" form. Refer to the [predefined roles overview](../reference/rbac.md#predefined-roles) for more information on roles.
 
     ![A form titled "Add team member". It has the fields "full name", "email", and "role". The role field is a radio button set with roles called "admin", "editor", and "viewer".](/img/user_admin_add_user_modal.png)
 

website/docs/how-to/how-to-create-and-assign-custom-root-roles.md

@@ -0,0 +1,36 @@
+---
+title: How to create and assign custom root roles
+---
+
+:::info availability
+
+Custom root roles were introduced in **Unleash 5.4** and are only available in Unleash Enterprise.
+
+:::
+
+
+This guide takes you through [how to create](#creating-custom-root-roles "how to create custom root roles") and [assign](#assigning-custom-root-roles "how to assign custom root roles") [custom root roles](../reference/rbac.md#custom-root-roles). Custom root roles allow you to fine-tune access rights and permissions to root resources in your Unleash instance.
+
+## Creating custom root roles
+
+### Step 1: Navigate to the custom root roles page {#create-step-1}
+
+Navigate to the _roles_ page in the admin UI (available at the URL `/admin/roles`). Use the _settings_ button in the navigation menu and select "roles".
+
+![The admin UI admin menu with the Roles item highlighted.](/img/create-crr-step-1.png)
+
+### Step 2: Click the "new root role" button. {#create-step-2}
+
+Use the "new root role" button to open the "new root role" form.
+
+![The "root roles" table with the "new root role" button highlighted.](/img/create-crr-step-2.png)
+
+### Step 3: Fill in the root role form {#create-step-3}
+
+Give the root role a name, a description, and the set of permissions you'd like it to have. For a full overview of all the options, consult the [custom root roles reference documentation](../reference/rbac.md#custom-root-roles).
+
+![The root role form filled with some example data, and the "add role" button highlighted at the bottom.](/img/create-crr-step-3.png)
+
+## Assigning custom root roles
+
+You can assign custom root roles just like you would assign any other [predefined root role](../reference/rbac.md#predefined-roles). Root roles can be assigned to users, [service accounts](../reference/service-accounts.md), and [groups](../reference/rbac.md#user-groups).

website/docs/how-to/how-to-create-service-accounts.mdx

@@ -26,7 +26,7 @@ Use the "new service account" button to open the "new service account" form.
 
 Give your new service account a name. After leaving the name field, the username field is pre-filled with a suggestion based on the name you entered, but you can change it to whatever you like.
 
-Select a [global role](https://docs.getunleash.io/reference/rbac#standard-roles) for your service account, which will define what your new service account will be allowed to do. The roles that you can assign to service accounts are the same ones that are available for regular users.
+Select a [root role](https://docs.getunleash.io/reference/rbac#predefined-roles) for your service account, which will define what your new service account will be allowed to do. The roles that you can assign to service accounts are the same ones that are available for regular users.
 
 ![The service account form filled with some example data, and the "add service account" button highlighted at the bottom.](/img/service-account-3.png)
 

website/docs/reference/api-tokens-and-client-keys.mdx

@@ -51,12 +51,12 @@ Project-level visibility and access to API tokens was introduced in Unleash 4.22
 
 By default, only admin users can create API tokens, and only admins can see their values.
 
-However, any [client](#client-tokens client tokens) and [front-end tokens](#front-end-tokens) that are applicable to a project, will also be visible to any members of that project that have the `READ_PROJECT_API_TOKEN` permission (all project members by default). 
+However, any [client](#client-tokens client tokens) and [front-end tokens](#front-end-tokens) that are applicable to a project, will also be visible to any members of that project that have the `READ_PROJECT_API_TOKEN` permission (all project members by default).
 
 Similarly, any project members with the `CREATE_PROJECT_API_TOKEN` permission can also create client and front-end tokens for that specific project ([how to create project API tokens](../how-to/how-to-create-project-api-tokens.mdx)).
 ### Admin tokens
 
-**Admin tokens** grant _full read and write access_ to all resources in the Unleash server API. Admin tokens have access to all projects, all environments, and all global resources (find out more about [resources in the RBAC document](../reference/rbac.md#core-principles)).
+**Admin tokens** grant _full read and write access_ to all resources in the Unleash server API. Admin tokens have access to all projects, all environments, and all root resources (find out more about [resources in the RBAC document](../reference/rbac.md#core-principles)).
 
 Use admin tokens to:
 

website/docs/reference/api/legacy/unleash/admin/user-admin.md

@@ -16,14 +16,14 @@ Will return all users and all available root roles for the Unleash instance.
 {
   "rootRoles": [
     {
-      "description": "Users with the global admin role have superuser access to Unleash and can perform any operation within the unleash platform.",
+      "description": "Users with the root admin role have superuser access to Unleash and can perform any operation within the unleash platform.",
       "id": 1,
       "name": "Admin",
       "project": null,
       "type": "root"
     },
     {
-      "description": "Users with this role have access most features in Unleash, but can not manage users and roles in the global scope. If a user with a global regular role creates a project, they will become a project admin and receive superuser rights within the context of that project.",
+      "description": "Users with this role have access most features in Unleash, but can not manage users and roles in the root scope. If a user with a regular root role creates a project, they will become a project admin and receive superuser rights within the context of that project.",
       "id": 2,
       "name": "Editor",
       "project": null,
@@ -64,7 +64,7 @@ Will return all users and all available root roles for the Unleash instance.
 }
 ```
 
-### Get a single users {#get-user}
+### Get a single user {#get-user}
 
 `GET https://unleash.host.com/api/admin/user-admin/:id`
 

website/docs/reference/change-requests.md

@@ -74,9 +74,9 @@ Change requests have their own set of environment-specific permissions that can
 - apply change requests
 - skip the change request flow **when using the API directly**
 
-None of the standard roles have any change request permissions, so you must create your own project roles to take advantage of change requests. In other words, even a user with the project "owner" role can not approve or apply change requests.
+None of the predefined roles have any change request permissions, so you must create your own project roles to take advantage of change requests. In other words, even a user with the project "owner" role can not approve or apply change requests.
 
-There is no permission to create change requests: **Anyone can create change requests**, even Unleash users with the [global viewer role](rbac.md#standard-roles). Change requests don't cause any changes until approved and applied by someone with the correct permissions.
+There is no permission to create change requests: **Anyone can create change requests**, even Unleash users with the [root viewer role](rbac.md#predefined-roles). Change requests don't cause any changes until approved and applied by someone with the correct permissions.
 
 ### Circumventing change requests