Mirrors/unleash.unleash
1
0
Fork 0
mirror of https://github.com/Unleash/unleash.git synced 2025-01-25 00:07:47 +01:00
Code Issues Projects Releases Wiki Activity

docs: custom root roles (#4451)

Browse Source 
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 <thomas@getunleash.ai>
This commit is contained in:
Nuno Góis 2023-08-10 08:21:58 +01:00 committed by GitHub
parent fe0c7087de
commit 95f4f641b5
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
25 changed files with 229 additions and 104 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
frontend/src/component/admin/roles/RoleForm/useRoleForm.ts
View File

@ -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,
};
};

13
frontend/src/component/admin/roles/RoleModal/RoleModal.tsx
View File

@ -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}
>

5
frontend/src/component/admin/users/CreateUser/CreateUser.tsx
View File

@ -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}
>

5
frontend/src/component/admin/users/EditUser/EditUser.tsx
View File

@ -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}
>

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

@ -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',

2
src/lib/openapi/spec/user-schema.ts
View File

@ -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,

2
src/lib/openapi/spec/users-schema.ts
View File

@ -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',
},

2
src/lib/routes/admin-api/user-admin.ts
View File

@ -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: {

20
src/migrations/20230808104232-update-root-roles-descriptions.js Normal file
View File

@ -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,
);
};

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

@ -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)

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

@ -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)

2
website/docs/how-to/how-to-add-sso-saml.md
View File

@ -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)

2
website/docs/how-to/how-to-add-users-to-unleash.md
View File

@ -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)

36
website/docs/how-to/how-to-create-and-assign-custom-root-roles.md Normal file
View File

@ -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).

2
website/docs/how-to/how-to-create-service-accounts.mdx
View File

@ -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)

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

@ -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:

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

@ -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`

4
website/docs/reference/change-requests.md
View File

@ -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

2
website/docs/reference/public-signup.mdx
View File

@ -2,7 +2,7 @@
title: Public Invite Links
---
Public invite links let you invite team members to your Unleash instance. Any user with an invite link can sign up to Unleash instance that created the link. The user will get the **viewer** role (refer to the [_standard roles_ section of the RBAC document](../reference/rbac.md#standard-roles) for more information on roles).
Public invite links let you invite team members to your Unleash instance. Any user with an invite link can sign up to Unleash instance that created the link. The user will get the **viewer** role (refer to the [predefined roles_ section of the RBAC document](../reference/rbac.md#predefined-roles) for more information on roles).
User who follow the invite link are taken directly to the Unleash sign-up page, where they can create an account.

200
website/docs/reference/rbac.md
View File

@ -9,7 +9,7 @@ This document forms the specifications for [Role-Based Access Control](https://e
Unleash has two levels in its hierarchy of resources:
1. **Global resources** - Everything that lives across the entire Unleash instance. Examples of this include:
1. **Root resources** - Everything that lives across the entire Unleash instance. Examples of this include:
- activation strategies
- context field definitions
- addon configurations
@ -19,22 +19,114 @@ Unleash has two levels in its hierarchy of resources:
![RBAC overview](/img/rbac.png)
Unleash v4 allows you control access to both global resources and individual project resources.
Unleash v4 allows you control access to both root resources and individual project resources.
## Standard roles
## Predefined roles
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 comes with a set of built-in predefined roles that you can use. The _root 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 root roles](#custom-root-roles) and [custom project roles](#custom-project-roles).
When you add a new user, you can assign them one of the global roles listed below.
When you add a new user, you can assign them one of the root roles listed below.
| 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 |
| **Admin** | Root | Users with the root admin role have superuser access to Unleash and can perform any operation within the Unleash platform. | All versions |
| **Editor** | Root | 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. | All versions |
| **Viewer** | Root | 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. | All versions |
| **Owner** | Project | 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. | 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 |
## Custom Root Roles
:::info availability
Custom root roles were introduced in **Unleash 5.4** and are only available in Unleash Enterprise.
:::
Custom root roles let you define your own root roles with a specific set of root permissions. The roles can then be assigned to entities (users, service accounts and groups) at the root level. This allows you to control access to resources in a more precise, fine-grained way. For a step-by-step walkthrough of how to create and assign custom root roles, refer to [_how to create and assign custom root roles_](../how-to/how-to-create-and-assign-custom-root-roles.md).
Each custom root role consists of:
- a **name** (required)
- a **role description** (required)
- a set of **root permissions** (required)
### Root permissions
You can assign the following root permissions:
#### Addon permissions
| Permission Name | Description |
|-----------------------|-----------------------------------|
| Create addons | Lets the user create addons. |
| Update addons | Lets the user update addons. |
| Delete addons | Lets the user delete addons. |
#### API token permissions
| Permission Name | Description |
|-----------------------|-----------------------------------|
| Read frontend API tokens | Lets the user read frontend API tokens. |
| Create frontend API tokens | Lets the user create frontend API tokens. |
| Update frontend API tokens | Lets the user update frontend API tokens. |
| Delete frontend API tokens | Lets the user delete frontend API tokens. |
| Read client API tokens | Lets the user read client API tokens. |
| Create client API tokens | Lets the user create client API tokens. |
| Update client API tokens | Lets the user update client API tokens. |
| Delete client API tokens | Lets the user delete client API tokens. |
#### Application permissions
| Permission Name | Description |
|-----------------------|-----------------------------------|
| Update applications | Lets the user update applications. |
#### Context field permissions
| Permission Name | Description |
|-----------------------|-----------------------------------|
| Create context fields | Lets the user create context fields. |
| Update context fields | Lets the user update context fields. |
| Delete context fields | Lets the user delete context fields. |
#### Project permissions
| Permission Name | Description |
|-----------------------|-----------------------------------|
| Create projects | Lets the user create projects. |
#### Role permissions
| Permission Name | Description |
|-----------------------|-----------------------------------|
| Read roles | Lets the user read roles. |
#### Segment permissions
| Permission Name | Description |
|-----------------------|-----------------------------------|
| Create segments | Lets the user create segments. |
| Edit segments | Lets the user edit segments. |
| Delete segments | Lets the user delete segments. |
#### Strategy permissions
| Permission Name | Description |
|-----------------------|-----------------------------------|
| Create strategies | Lets the user create strategies. |
| Update strategies | Lets the user update strategies. |
| Delete strategies | Lets the user delete strategies. |
#### Tag type permissions
| Permission Name | Description |
|-----------------------|-----------------------------------|
| Update tag types | Lets the user update tag types. |
| Delete tag types | Lets the user delete tag types. |
## Custom Project Roles
:::info availability
@ -43,82 +135,42 @@ Custom project roles were introduced in **Unleash 4.6** and are only available i
:::
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).
Custom project roles let you define your own project 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).
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)
- a **role description** (required)
- a set of **project and / or environment permissions** (required)
### Project permissions
You can assign the following project permissions. The permissions will be valid across all of the project's environments.
- **update the project**
Lets the user update project settings, such as enabling/disabling environments, add users, etc.
- **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. (Deprecated with v4.21 in favor of environment-specific permissions for working with variants[^1].)
| Permission | Description |
|--------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|
| **update the project** | Lets the user update project settings, such as enabling/disabling environments, add users, etc. |
| **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 **cannot 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. (Deprecated with v4.21 in favor of environment-specific permissions for working with variants[^1].) |
### 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.
- **update variants**
Lets the user create, edit and remove variants within the environment.
- **approve a change request**
Lets the user approve [change requests](change-requests.md) in the environment.
- **apply a change request**
Lets the user apply change requests in the environment.
- **skip change requests**
Lets the user ignore change request requirements. This applies **only when using the API** directly; when using the admin UI, users with this permission will still need to go through the normal change request flow. You can find more details in the section on [circumventing change requests](change-requests.md#circumventing-change-requests).
| Permission | Description |
|---------------------------------------|--------------------------------------------------------------------------------------------------|
| **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. |
| **update variants** | Lets the user create, edit and remove variants within the environment. |
| **approve a change request** | Lets the user approve [change requests](change-requests.md) in the environment. |
| **apply a change request** | Lets the user apply change requests in the environment. |
| **skip change requests** | Lets the user ignore change request requirements. This applies **only when using the API** directly; when using the admin UI, users with this permission will still need to go through the normal change request flow. You can find more details in the section on [circumventing change requests](change-requests.md#circumventing-change-requests). |
## User Groups
@ -140,9 +192,9 @@ A user group consists of the following:
Groups do nothing on their own. They must either be given a root role directly or a role on a project to assign permissions.
Groups that do not have a root role need to be assigned a role on a project to be useful. You can assign both standard roles and custom project roles to groups.
Groups that do not have a root role need to be assigned a role on a project to be useful. You can assign both predefined roles and custom project roles to groups.
Groups that *do* have a root role can't be assigned to a project. Any user that is a member of a group with a root role will inherit that root role's permissions globally.
Groups that *do* have a root role can't be assigned to a project. Any user that is a member of a group with a root role will inherit that root role's permissions on the root level.
While a user can only have one role in a given project, a user may belong to multiple groups, and each of those groups may be given a role on a project. In the case where a given user is given permissions through more than one group, the user will inherit most permissive permissions of all their groups in that project.
@ -150,7 +202,7 @@ While a user can only have one role in a given project, a user may belong to mul
:::info availability
User group syncing is planned to be released in Unleash 4.18 and will be available for enterprise customers.
User group syncing is planned to be released in Unleash 4.18 and will be available for Enterprise customers.
:::

8
website/docs/topics/the-anatomy-of-unleash.mdx
View File

@ -8,9 +8,9 @@ This guide's purpose is to give you a conceptual overview of how Unleash works.
The end of this guide presents a [short use case, explaining how you might configure Unleash](#use-case) to start working with feature toggles.
## The global level
## The root level
Some things in Unleash are configured and defined on the global level. These options apply across the entire Unleash instance. The most important global configuration options for day-to-day operations are:
Some things in Unleash are configured and defined on the root level. These options apply across the entire Unleash instance. The most important root configuration options for day-to-day operations are:
- [API access tokens](../reference/api-tokens-and-client-keys.mdx)
- [Projects](../reference/projects.md)
@ -18,7 +18,7 @@ Some things in Unleash are configured and defined on the global level. These opt
- [Strategy types](../reference/activation-strategies.md) (including [custom activation strategy types](../reference/custom-activation-strategies.md))
- [Tag types](../reference/tags.md)
- [Unleash context](../reference/unleash-context.md) fields (including [custom context fields](../reference/unleash-context.md#custom-context-fields))
- Users, [user groups](../reference/rbac.md#user-groups) and [global roles](../reference/rbac.md)
- Users, [user groups](../reference/rbac.md#user-groups) and [roles](../reference/rbac.md)
## Projects
@ -37,7 +37,7 @@ Pro and Enterprise customers can create, rename, and delete projects as they wis
[**Environments**](../reference/environments.md) in Unleash let you change how a feature toggle works in your application’s different environments. For instance, while you are developing a feature, it’s likely that you’ll want it to be available in your development environment, but not in your production environment: environments let you do that. You might also want to enable a feature for only some users in your development environment, but no users in your production environment: environments let you do that.
Environments exist on two different levels within Unleash. The set of **all available environments is defined on the global level**. Additionally, **each project** can choose which of these global environments should be **available on the project level**. The set of environments available to any given project is **always a subset** of the set of globally available environments.
Environments exist on two different levels within Unleash. The set of **all available environments is defined on the root level**. Additionally, **each project** can choose which of these root environments should be **available on the project level**. The set of environments available to any given project is **always a subset** of the set of all available environments at the root level.
Each project must always have **at least one** active environment.

1
website/sidebars.js
View File

@ -123,6 +123,7 @@ module.exports = {
label: 'Users and permissions',
items: [
'how-to/how-to-add-users-to-unleash',
'how-to/how-to-create-and-assign-custom-root-roles',
'how-to/how-to-create-and-assign-custom-project-roles',
'how-to/how-to-create-and-manage-user-groups',
'how-to/how-to-set-up-group-sso-sync',

BIN
website/static/img/create-crr-step-1.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 46 KiB

BIN
website/static/img/create-crr-step-2.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 42 KiB

BIN
website/static/img/create-crr-step-3.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 144 KiB