Merge pull request #1238 from Unleash/docs/custom-project-roles

docs: describe new custom project roles

website/docs/deploy/configuring-unleash.md

@@ -67,31 +67,6 @@ unleash.start(unleashOptions);
 
 **Available Unleash options include:**
 
-- **databaseUrl** - (_deprecated_) the postgres database url to connect to. Only used if _db_ object is not specified, and overrides the _db_ object and any environment variables that change parts of it (like `DATABASE_SSL`). Should include username/password. This value may also be set via the `DATABASE_URL` environment variable. Alternatively, if you would like to read the database url from a file, you may set the `DATABASE_URL_FILE` environment variable with the full file path. The contents of the file must be the database url exactly.
-- **db** - The database configuration object taking the following properties:
-  - _user_ - the database username (`DATABASE_USERNAME`)
-  - _password_ - the database password (`DATABASE_PASSWORD`)
-  - _host_ - the database hostname (`DATABASE_HOST`)
-  - _port_ - the database port defaults to 5432 (`DATABASE_PORT`)
-  - _database_ - the database name to be used (`DATABASE_NAME`)
-  - _ssl_ - an object describing ssl options, see https://node-postgres.com/features/ssl (`DATABASE_SSL`, as a stringified json object)
-  - _schema_ - the postgres database schema to use. Defaults to 'public'. (`DATABASE_SCHEMA`)
-  - _version_ - the postgres database version. Used to connect a non-standard database. Defaults to `undefined`, which let the underlying adapter to detect the version automatically. (`DATABASE_VERSION`)
-  - _pool_ - an object describing pool options, see https://knexjs.org/#Installation-pooling. We support the following three fields:
-    - _min_ - minimum connections in connections pool (defaults to 0) (`DATABASE_POOL_MIN`)
-    - _max_ - maximum connections in connections pool (defaults to 4) (`DATABASE_POOL_MAX`)
-    - _idleTimeoutMillis_ - time in milliseconds a connection must be idle before being marked as a candidate for eviction (defaults to 30000) (`DATABASE_POOL_IDLE_TIMEOUT_MS`)
-- **server** - The server config object taking the following properties
-  - _port_ - which port the unleash-server should bind to. If port is omitted or is 0, the operating system will assign an arbitrary unused port. Will be ignored if pipe is specified. This value may also be set via the `HTTP_PORT` environment variable
-  - _host_ - which host the unleash-server should bind to. If host is omitted, the server will accept connections on the unspecified IPv6 address (::) when IPv6 is available, or the unspecified IPv4 address (0.0.0.0) otherwise. This value may also be set via the `HTTP_HOST` environment variable
-  - _pipe_ - parameter to identify IPC endpoints. See https://nodejs.org/api/net.html#net_identifying_paths_for_ipc_connections for more details
-  - _serverMetrics_ (boolean) - use this option to turn on/off prometheus metrics.
-  - _baseUriPath_ (string) - use to register a base path for all routes on the application. For example `/my/unleash/base` (note the starting /). Defaults to `/`. Can also be configured through the environment variable `BASE_URI_PATH`.
-  - _unleashUrl_ (string) - Used to specify the official URL this instance of Unleash can be accessed at for an end user. Can also be configured through the environment variable `UNLEASH_URL`.
-  - _gracefulShutdownEnable_: (boolean) - Used to control if Unleash should shutdown gracefully (close connections, stop tasks,). Defaults to true. `GRACEFUL_SHUTDOWN_ENABLE`
-  - _gracefulShutdownTimeout_: (number) - Used to control the timeout, in milliseconds, for shutdown Unleash gracefully. Will kill all connections regardless if this timeout is exceeded. Defaults to 1000ms `GRACEFUL_SHUTDOWN_TIMEOUT`
-- **preHook** (function) - this is a hook if you need to provide any middlewares to express before `unleash` adds any. Express app instance is injected as first argument.
-- **preRouterHook** (function) - use this to register custom express middlewares before the `unleash` specific routers are added.
 - **authentication** - (object) - An object for configuring/implementing custom admin authentication
   - enableApiToken (boolean) - Should unleash require API tokens for access? Defaults to `true`
   - type (string) What kind of authentication to use. Possible values
@@ -115,14 +90,21 @@ unleash.start(unleashOptions);
       The tokens can be of any API token type. Note that _admin_ tokens **must** target all environments and projects (i.e. use `'*'` for `environments` and `project` and start the secret with `*:*.`).
 
       You can also use the environment variable `INIT_ADMIN_API_TOKENS` to create API tokens on startup. This variable should be set to a comma-separated list of API tokens to initialize (for instance `*:*.some-random-string, *:*.some-other-token`). With the environment variable, all tokens will be created as admin tokens and Unleash will assign a username automatically.
-- **ui** (object) - Set of UI specific overrides. You may set the following keys: `environment`, `slogan`.
-- **getLogger** (function) - Used to register a [custom log provider](#how-do-i-configure-the-log-output).
-- **logLevel** (`debug` | `info` | `warn` | `error` | `fatal`) - The lowest level to log at, also configurable using environment variable `LOG_LEVEL`.
-- **eventHook** (`function(event, data)`) - If provided, this function will be invoked whenever a feature is mutated. The possible values for `event` are `'feature-created'`, `'feature-updated'`, `'feature-archived'`, `'feature-revived'`. The `data` argument contains information about the mutation. Its fields are `type` (string) - the event type (same as `event`); `createdBy` (string) - the user who performed the mutation; `data` - the contents of the change. The contents in `data` differs based on the event type; For `'feature-archived'` and `'feature-revived'`, the only field will be `name` - the name of the feature. For `'feature-created'` and `'feature-updated'` the data follows a schema defined in the code [here](https://github.com/Unleash/unleash/blob/master/src/lib/services/feature-schema.js#L65). See an [api here](/api/admin/events).
-- **secureHeaders** (boolean) - use this to enable security headers (HSTS, CSP, etc) when serving Unleash from HTTPS. Can also be configured through the environment variable `SECURE_HEADERS`.
-- **versionCheck** - the object deciding where to check for latest version
-  - `url` - The url to check version (Defaults to `https://version.unleash.run`) - Overridable with (`UNLEASH_VERSION_URL`)
-  - `enable` - Whether version checking is enabled (defaults to true) - Overridable with (`CHECK_VERSION`) (if anything other than `true`, does not check)
+- **databaseUrl** - (_deprecated_) the postgres database url to connect to. Only used if _db_ object is not specified, and overrides the _db_ object and any environment variables that change parts of it (like `DATABASE_SSL`). Should include username/password. This value may also be set via the `DATABASE_URL` environment variable. Alternatively, if you would like to read the database url from a file, you may set the `DATABASE_URL_FILE` environment variable with the full file path. The contents of the file must be the database url exactly.
+- **db** - The database configuration object taking the following properties:
+  - _user_ - the database username (`DATABASE_USERNAME`)
+  - _password_ - the database password (`DATABASE_PASSWORD`)
+  - _host_ - the database hostname (`DATABASE_HOST`)
+  - _port_ - the database port defaults to 5432 (`DATABASE_PORT`)
+  - _database_ - the database name to be used (`DATABASE_NAME`)
+  - _ssl_ - an object describing ssl options, see https://node-postgres.com/features/ssl (`DATABASE_SSL`, as a stringified json object)
+  - _schema_ - the postgres database schema to use. Defaults to 'public'. (`DATABASE_SCHEMA`)
+  - _version_ - the postgres database version. Used to connect a non-standard database. Defaults to `undefined`, which let the underlying adapter to detect the version automatically. (`DATABASE_VERSION`)
+  - _pool_ - an object describing pool options, see https://knexjs.org/#Installation-pooling. We support the following three fields:
+    - _min_ - minimum connections in connections pool (defaults to 0) (`DATABASE_POOL_MIN`)
+    - _max_ - maximum connections in connections pool (defaults to 4) (`DATABASE_POOL_MAX`)
+    - _idleTimeoutMillis_ - time in milliseconds a connection must be idle before being marked as a candidate for eviction (defaults to 30000) (`DATABASE_POOL_IDLE_TIMEOUT_MS`)
+- **disableLegacyFeaturesApi** (boolean) - whether to disable the [legacy features API](../api/admin/feature-toggles-api.md). Defaults to `false` (`DISABLE_LEGACY_FEATURES_API`). Introduced in Unleash 4.6.
 - **email** - the email object configuring an SMTP server for sending welcome mails and password reset mails
   - `host` - The server URL to your SMTP server
   - `port` - Which port the SMTP server is running on. Defaults to 465 (Secure SMTP)
@@ -130,6 +112,25 @@ unleash.start(unleashOptions);
   - `sender` - Which email should be set as sender of mails being sent from Unleash?
   - `smtpuser` - Username for your SMTP server
   - `smtppass` - Password for your SMTP server
+- **eventHook** (`function(event, data)`) - If provided, this function will be invoked whenever a feature is mutated. The possible values for `event` are `'feature-created'`, `'feature-updated'`, `'feature-archived'`, `'feature-revived'`. The `data` argument contains information about the mutation. Its fields are `type` (string) - the event type (same as `event`); `createdBy` (string) - the user who performed the mutation; `data` - the contents of the change. The contents in `data` differs based on the event type; For `'feature-archived'` and `'feature-revived'`, the only field will be `name` - the name of the feature. For `'feature-created'` and `'feature-updated'` the data follows a schema defined in the code [here](https://github.com/Unleash/unleash/blob/master/src/lib/services/feature-schema.js#L65). See an [api here](/api/admin/events).
+- **getLogger** (function) - Used to register a [custom log provider](#how-do-i-configure-the-log-output).
+- **logLevel** (`debug` | `info` | `warn` | `error` | `fatal`) - The lowest level to log at, also configurable using environment variable `LOG_LEVEL`.
+- **preHook** (function) - this is a hook if you need to provide any middlewares to express before `unleash` adds any. Express app instance is injected as first argument.
+- **preRouterHook** (function) - use this to register custom express middlewares before the `unleash` specific routers are added.
+- **secureHeaders** (boolean) - use this to enable security headers (HSTS, CSP, etc) when serving Unleash from HTTPS. Can also be configured through the environment variable `SECURE_HEADERS`.
+- **server** - The server config object taking the following properties
+  - _port_ - which port the unleash-server should bind to. If port is omitted or is 0, the operating system will assign an arbitrary unused port. Will be ignored if pipe is specified. This value may also be set via the `HTTP_PORT` environment variable
+  - _host_ - which host the unleash-server should bind to. If host is omitted, the server will accept connections on the unspecified IPv6 address (::) when IPv6 is available, or the unspecified IPv4 address (0.0.0.0) otherwise. This value may also be set via the `HTTP_HOST` environment variable
+  - _pipe_ - parameter to identify IPC endpoints. See https://nodejs.org/api/net.html#net_identifying_paths_for_ipc_connections for more details
+  - _serverMetrics_ (boolean) - use this option to turn on/off prometheus metrics.
+  - _baseUriPath_ (string) - use to register a base path for all routes on the application. For example `/my/unleash/base` (note the starting /). Defaults to `/`. Can also be configured through the environment variable `BASE_URI_PATH`.
+  - _unleashUrl_ (string) - Used to specify the official URL this instance of Unleash can be accessed at for an end user. Can also be configured through the environment variable `UNLEASH_URL`.
+  - _gracefulShutdownEnable_: (boolean) - Used to control if Unleash should shutdown gracefully (close connections, stop tasks,). Defaults to true. `GRACEFUL_SHUTDOWN_ENABLE`
+  - _gracefulShutdownTimeout_: (number) - Used to control the timeout, in milliseconds, for shutdown Unleash gracefully. Will kill all connections regardless if this timeout is exceeded. Defaults to 1000ms `GRACEFUL_SHUTDOWN_TIMEOUT`
+- **ui** (object) - Set of UI specific overrides. You may set the following keys: `environment`, `slogan`.
+- **versionCheck** - the object deciding where to check for latest version
+  - `url` - The url to check version (Defaults to `https://version.unleash.run`) - Overridable with (`UNLEASH_VERSION_URL`)
+  - `enable` - Whether version checking is enabled (defaults to true) - Overridable with (`CHECK_VERSION`) (if anything other than `true`, does not check)
 
 ### Disabling Auto-Start {#disabling-auto-start}
 

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

@@ -0,0 +1,34 @@
+---
+title: How to create and assign custom project roles
+---
+:::info availability
+Custom project roles were introduced in **Unleash 4.6** and are only available in Unleash Enterprise.
+:::
+
+This guide takes you through [how to create](#creating-custom-project-roles "how to create custom project roles") and [assign](#assigning-custom-project-roles "how to assign custom project roles") [custom project roles](../user_guide/rbac.md#custom-project-roles).
+
+## Creating custom project roles
+
+To create custom project roles:
+
+1. Navigate to the custom project roles page by using the admin menu (the gear symbol) and navigating to users.
+    ![A visual representation of the current step: the Unleash Admin UI with the steps highlighted.](/img/create-cpr-step-1.png)
+2. Navigate to the "project roles" tab.
+    ![The admin/roles screen, with the project roles tab highlighted. The page shows a table of project roles with their descriptions.](/img/create-cpr-step-2.png)
+3. Use the "new project role" button to open the role creation form.
+    ![The visual position of the 'new project role' button on the page.](/img/create-cpr-step-3.png)
+4. Give the role a name, an optional description, and the set of permissions you'd like it to have. For a full overview of all the options, consult the [custom project roles reference documentation](../user_guide/rbac.md#custom-project-roles).
+    ![The project role creation form filled in with details for a "developer" role. To the left is the equivalent cURL command you could run if you wanted to use the API instead of the form.](/img/create-cpr-step-4.png)
+
+## Assigning custom project roles
+
+To assign a custom project role to a user:
+1. Navigate to the project you want to assign the user a role in.
+    ![The steps to navigate to a project: use the 'projects' navigation item and select your project.](/img/assign-cpr-step-1.png)
+2. Navigate to the project's _access_ page.
+    ![A project overview with the 'access' tab highlighted.](/img/assign-cpr-step-2.png)
+3. This step depends on whether the user has already been added to the project or not:
+    - If the user has already been added to the project, select the new role you want to give them from the dropdown menu next to their name.
+        ![A list of users with access to the current project. To the right of each user is a dropdown input labeled role.](/img/assign-cpr-step-3a.png)
+    - If the user _hasn't_ been added to the project, add them via the 'add user' form. Select the role you want to give them from the role field.
+        ![Adding a user to a project. The add user form is filled out with data for an "Alexis". The Role input is open and the custom "Developer" role is highlighted.](/img/assign-cpr-step-3b.png)

website/docs/user_guide/rbac.md

@@ -5,11 +5,11 @@ title: Role-based Access control
 
 This document forms the specifications for [Role-Based Access Control](https://en.wikipedia.org/wiki/Role-based_access_control) which was introduced as part of the **Unleash v4 release**.
 
-### Core principles {#core-principles}
+## Core principles {#core-principles}
 
 Unleash has two levels in it’s hierarchy of resources:
 
-1. **Root resources** - Everything that lives across the entire Unleash instance. Examples of this includes:
+1. **Global resources** - Everything that lives across the entire Unleash instance. Examples of this includes:
    - activation strategies
    - context field definitions
    - addon configurations
@@ -19,33 +19,84 @@ Unleash has two levels in it’s hierarchy of resources:
 
 ![RBAC overview](/img/rbac.png)
 
-Unleash v4 allows you control access to both "root resources" and individual project resources.
+Unleash v4 allows you control access to both global resources and individual project resources.
 
-### Root Roles {#root-roles}
+## Standard roles
 
-> Available for Unleash Open-Source and Unleash Enterprise.
+Unleash comes with a set of built-in roles that you can use. The _global roles_ are available to all Unleash users, while the _project-based roles_ are only available to Pro and Enterprise users. The below table lists the roles, what they do, and what plans they are available in. Additionally, enterprise users can create their own [custom project roles](#custom-project-roles).
 
-Unleash will come with three "root" role out of the box:
+When you add a new user, you can assign them one of the global roles listed below.
 
-- **Admin** - Used to administer the Unleash instance. Is allowed to add/remove users, add them to roles and update role permissions.
-- **Editor** - Represent users with typical read and write access to Unleash. They will typically be allowed to create new projects (for enterprise), create feature toggles on the "default" project, configure context fields etc. They will not be able to add/remove users or roles.
-- **Viewer** - Users with this role are only allowed to read resources in Unleash. They might be added as collaborators to specific projects.
+| Role       | Scope   | Description                                                                                                                                                                                                                                                         | Availability       |
+|------------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------|
+| **Admin**  | Global  | Users with the global admin role have superuser access to Unleash and can perform any operation within the Unleash platform.                                                                                                                                        | All versions       |
+| **Editor** | Global  | Users with the editor role have access to most features in Unleash but can not manage users and roles in the global 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.           | All versions       |
+| **Viewer** | Global  | Users with the viewer role can read global resources in Unleash.                                                                                                                                                                                                    | All versions       |
+| **Owner**  | Project | Users with this 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. | Pro and Enterprise |
+| **Member** | Project | 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.                               | Pro and Enterprise |
 
-### Project {#project}
+## Custom Project Roles
 
-> Project roles are part of Unleash Enterprise.
+:::info availability
+Custom project roles were introduced in **Unleash 4.6** and are only available in Unleash Enterprise.
+:::
 
-Per project two roles are now available:
+Custom project roles let you define your own roles with a specific set of project permissions down to the environment level. The roles can then be assigned to users in specific projects. All users have viewer access to all projects and resources, but must be assigned a project role to be allowed to edit a project's resources. For a step-by-step walkthrough of how to create and assign custom project roles, see [_how to create and assign custom project roles_](../how-to/how-to-create-and-assign-custom-project-roles.md).
 
-- **Owner** - Allowed to update the project. This includes adding and removing project members and their role.
-- **Member** - Allowed to create and update feature toggles within the project. They can not update the project itself
+Each custom project role consists of:
+- a **name** (required)
+- a **role description** (optional)
+- a set of **project permissions** (optional)
+- a set of **environment permissions** (optional)
 
-It is important to highlight that we have not introduced a Viewer role on the project level. We believe that all users in Unleash should be able to to View all feature toggles and configuration within an organization. (If we learn this not to be the case we can add a separate role for READ access later).
+### Project permissions
 
-### Custom Roles {#custom-roles}
+You can assign the following project permissions. The permissions will be valid across all of the project's environments.
 
-> Will only be introduced for Unleash Enterprise.
+- **update the project**
 
-In a later iteration we will introduce the concept of "custom roles". This will allow full customization to meet internal needs of larger organisations. We believe these should be able to define access across both “root resources” and specific projects resources. We need further investigation with customers before we land custom roles.
+  Lets the user update project settings, such as enabling/disabling environments, add users, etc.
 
-Please let us know if you have feedback or ideas on how custom roles should work in order to solve your company needs.
+- **delete the project**
+
+  Lets the user delete the project.
+
+- **create feature toggles within the project**
+
+  Lets the user create feature toggles within the project and create variants for said toggle. Note that they **can not assign strategies** to toggles without having the _create activation strategy_ permission for the corresponding environment.
+
+- **update feature toggles within the project**
+
+  Lets the user update feature toggle descriptions; mark toggles as stale / not stale; add, update, and remove toggle tags; and update toggle variants within the project.
+
+- **delete feature toggles within the project**
+
+  Lets the user archive feature toggles within the project.
+
+- **change feature toggle project**
+
+  Lets the user move toggles to other projects they have access to.
+
+- **create/edit variants**
+
+  Lets the user create and edit variants within the project.
+
+### Environment permissions
+
+You can assign the following permissions on a per-environment level within the project:
+
+- **create activation strategies**
+
+  Lets the user assign feature toggle activation strategies within the environment.
+
+- **update activation strategies**
+
+  Lets the user update feature toggle activation strategies within the environment.
+
+- **delete activation strategies**
+
+  Lets the user delete feature toggle activation strategies within the environment.
+
+- **enable/disable toggles**
+
+  Lets the user enable and disable toggles within the environment.

website/sidebars.js

@@ -94,6 +94,7 @@ module.exports = {
         ],
         "How-to guides": [
             "how-to/how-to-add-strategy-constraints",
+            "how-to/how-to-create-and-assign-custom-project-roles",
             "how-to/how-to-define-custom-context-fields",
             "how-to/how-to-use-custom-strategies",
         ]