Skip to content

Commit 19d5af9

Browse files
rolodatorolodato
authored
docs: Deprecate group-level permissions. Rewrite RBAC docs and add Mermaid diagrams (#4469)
1 parent 36e634c commit 19d5af9

File tree

5 files changed

+3972
-1887
lines changed

5 files changed

+3972
-1887
lines changed

‎docs/docs/system-administration/rbac.md

+134-61
Original file line numberDiff line numberDiff line change
@@ -1,100 +1,173 @@
11
---
2-
title: Role Based Access Control
2+
title: Role-based access control
33
---
44

5-
Flagsmith provides fine-grained permissions to help larger teams manage access and roles across organisations, projects
6-
and environments.
7-
85
:::info
96

10-
The Permissions/Role Based Access features of Flagsmith are _not_ part of the Open Source version. If you want to use
11-
these features as part of a self hosted/on premise solution, please [get in touch](https://flagsmith.com/contact-us/).
7+
Role-based access control requires an [Enterprise subscription](https://www.flagsmith.com/pricing).
128

139
:::
1410

15-
## Users, Groups, and Roles
11+
Role-based access control (RBAC) provides fine-grained access management of Flagsmith resources. Using RBAC, you can
12+
ensure users only have the access they need within your Flagsmith organisation.
1613

17-
Permissions can be assigned to Flagsmith individual users, groups, or roles.
14+
For example, RBAC allows you to achieve the following scenarios:
1815

19-
### Users
16+
- Only allow certain users to modify your production environments.
17+
- Grant a default set of permissions to all users that join your Flagsmith organisation.
18+
- Lock down an [Admin API](/clients/rest/#private-admin-api-endpoints) key to a specific set of permissions.
19+
- Provide Flagsmith permissions based on your enterprise identity provider's groups when using
20+
[SAML single sign-on](/system-administration/authentication/SAML/).
2021

21-
Flagsmith Users can be defined as Organisation Administrators or Users. Organisation Administrator is effectively a
22-
super-user role, and gives full read/write access to every Project, Environment, Flag, Remote Config and Segment within
23-
that Organisation.
22+
To add users to your Flagsmith organisation or to manage user permissions, click on your organisation name in the top
23+
left and open the **Users and Permissions** tab.
2424

25-
Users that are not Organisation Administrators must have permissions assigned to them manually at the relevant levels.
25+
## Core concepts
2626

27-
### Groups
27+
The diagram below shows an overview of how permissions are assigned within your Flagsmith organisation:
2828

29-
Groups are a convenient way to manage permissions for multiple Flagsmith users. Groups can contain any number of
30-
Flagsmith users. You can create groups with the Organisation Settings page.
29+
<div style={{textAlign: 'center'}}>
30+
```mermaid
31+
graph LR;
32+
R[Custom roles] -->|Assigned to| G[Groups];
33+
B[Built-in role] -->|Assigned to| U[Users];
34+
R -->|Assigned to| U;
35+
R -->|Assigned to| A[Admin API keys];
36+
G -->|Contains many| U;
37+
```
3138

32-
Members of a group can be designated as an admin for that group. As a group admin, users can manage the membership for
33-
that group, but not the permissions the group has on other entities.
39+
</div>
3440

3541
### Roles
3642

37-
A _Role_ is an entity to which you can attach a set of permissions. Permissions can allow privileges at Organization,
38-
Project, and Environment levels. You can assign a role, along with its associated permissions, to a User or Group. You
39-
will also be able to assign API keys to a Role in future versions.
43+
A role is a set of permissions that, when assigned, allows performing specific actions on your organisation, projects or
44+
project environments.
45+
46+
**Built-in roles** are predefined by Flagsmith and cannot be modified. All users in your organisation have one of the
47+
following built-in roles:
48+
49+
- _Organisation Administrator_ grants full access to everything in your Flagsmith organisation.
50+
- _User_ grants no access and requires you to assign permissions using custom roles and/or groups.
51+
52+
**Custom roles** can be assigned to users, groups or [Admin API](/clients/rest/#private-admin-api-endpoints) keys. Any
53+
number of custom roles can be created and assigned.
54+
55+
Creating, modifying or assigning roles requires organisation administrator permissions.
56+
57+
### Groups
58+
59+
A group is a collection of users. If a custom role is assigned to a group, the role's permissions will be granted to all
60+
group members. Users can belong to any number of groups.
61+
62+
Creating or modifying existing groups requires organisation administrator permissions.
63+
64+
Permissions to add or remove users from groups can be granted in two ways:
65+
66+
- The _manage group membership_ permission allows modifying any group's membership
67+
- A _group admin_ can manage membership only for that group
68+
69+
## Add users to your organisation
70+
71+
You can add users to your organisation by sending them an invitation email from Flagsmith, or by sharing an invitation
72+
link directly with them. Both options require organisation administrator permissions, and are available from **Users and
73+
Permissions > Members**.
74+
75+
Users can also join your organisation directly by logging in to Flagsmith using
76+
[single sign-on](/system-administration/authentication/SAML/).
77+
78+
### Email invites
79+
80+
:::info
81+
82+
If you are self-hosting Flagsmith, you must
83+
[configure an email provider](/deployment/hosting/locally-api#email-environment-variables) before using email invites.
84+
85+
:::
86+
87+
To send invitation emails to specific users, click on **Invite members**. Then, fill in the email address and built-in
88+
role of each user you want to invite.
89+
90+
When a user accepts their email invitation, they will be prompted to sign up for a Flagsmith account, or they can choose
91+
to log in if they already have an account with the same email address.
92+
93+
Users who have not yet accepted their invitations are listed in the "Pending invites" section at the bottom of this
94+
page. From here you can also resend or revoke any pending invitations.
95+
96+
### Invitation links
97+
98+
:::warning
99+
100+
Anyone with an invitation link can join your Flagsmith organisation at any time. Share these links with caution and
101+
regenerate them if they are compromised.
102+
103+
:::
40104

41-
#### Creating a Role
105+
Direct links to join your organisation can be found in the **Team Members** section of this page. One direct link is
106+
available for each built-in role that users will have when joining your organisation.
42107

43-
You can create a Role in the Organisation Settings page.
108+
## Provision permissions
44109

45-
#### Add Permissions to a Role
110+
If a user joins your organisation with the built-in _User_ role, they will not have any permissions to view or change
111+
anything in your Flagsmith organisation. You can provide default fine-grained permissions to users with any of these
112+
options:
46113

47-
Once the role is created you can assign the corresponding permissions.
114+
- Add users by default to a group. When creating or editing a group, select the **Add new users by default** option.
115+
When a user logs in for the first time to your organisation, they will automatically be added to all groups that have
116+
this option enabled.
117+
- [Use existing groups from your enterprise identity provider](/system-administration/authentication/SAML/#using-groups-from-your-saml-idp).
118+
Any time a user logs in using single sign-on, they will be made a member of any groups with matching external IDs.
48119

49-
**E.g. Add Project permission:**
120+
## Deprecated features
50121

51-
- Choose a Role.
52-
- Go to the Projects tab.
53-
- Select a Project and enable the relevant permissions.
122+
Groups can grant permissions directly to their members in the same way that roles do. This functionality was deprecated
123+
in Flagsmith 2.137.0. To grant permissions to all members of a group, create a role with the desired permissions and
124+
assign it to the group instead.
54125

55-
### Assign Role to Users or Groups
126+
Assigning roles to groups has several benefits over assigning permissions directly to a group:
56127

57-
After creating the Role, you can assign it to Users or Groups.
128+
- Roles can be assigned to Admin API keys, but Admin API keys cannot belong to groups.
129+
- If you need multiple groups or users with similar permissions, the common permissions can be defined in a role and
130+
assigned to multiple groups or users instead of being duplicated.
131+
- Having roles as the single place where permissions are defined makes auditing permissions easier.
58132

59-
**E.g. Assign role to a user:**
133+
## Permissions reference
60134

61-
- Choose a role.
62-
- Go to the Members tab.
63-
- Select the Users tab.
64-
- Click assign role to user button and select a user.
135+
Permissions can be assigned at four levels: user group, organisation, project, and environment.
65136

66-
## Permissions
137+
### User group
67138

68-
Permissions can be assigned at 3 levels: Organisation, Project, and Environment.
139+
| Permission | Ability |
140+
| ----------- | ------------------------------------------------ |
141+
| Group Admin | Allows adding or removing users from this group. |
69142

70143
### Organisation
71144

72-
| **Permission** | **Ability** |
73-
| ------------------ | --------------------------------------------------------------------------- |
74-
| Create Project | Allows the user to create Projects in the given Organisation |
75-
| Manage User Groups | Allows the user to manage the Groups in the Organisation and their members. |
145+
| Permission | Ability |
146+
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
147+
| Create Project | Allows creating projects in the organisation. Users are automatically granted Administrator permissions on any projects they create. |
148+
| Manage User Groups | Allows adding or removing users from any group. |
76149

77150
### Project
78151

79-
| **Permission** | **Ability** |
80-
| ------------------ | ------------------------------------------------------------------------------------------ |
81-
| Administrator | Full Read/Write over all Environments, Feature Flag, Remote Config, Segment and Tag values |
82-
| View Project | Can view the Project within their account |
83-
| Create Environment | Can create new Environments within the Project |
84-
| Create Feature | Can create a new Feature / Remote Config |
85-
| Delete Feature | Can remove an existing Feature / Remote Config entirely from the Project |
86-
| Manage Segments | Can create, delete and edit Segments within the Project |
87-
| View audit log | Allows the user to view the audit logs for this Project. |
152+
| Permission | Ability |
153+
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
154+
| Administrator | Grants full read and write access to all environments, features and segments. |
155+
| View Project | Allows viewing this project. The project is hidden from users without this permission. |
156+
| Create Environment | Allows creating new environments in this project. Users are automatically granted Administrator permissions on any environments they create. |
157+
| Create Feature | Allows creating new features in all environments. |
158+
| Delete Feature | Allows deleting features from all environments. |
159+
| Manage Segments | Grants write access to segments in this project. |
160+
| View audit log | Allows viewing all audit log entries for this project. |
88161

89162
### Environment
90163

91-
| **Permission** | **Ability** |
92-
| ------------------------ | --------------------------------------------------------------- |
93-
| Administrator | Can modify Feature Flag, Remote Config and Segment values |
94-
| View Environment | Can see the Environment within their account |
95-
| Update Feature State | Update the state or value for a given feature |
96-
| Manage Identities | View and update Identities |
97-
| Manage Segment Overrides | Permission to manage segment overrides in the given environment |
98-
| Create Change Request | Creating a new Change Request |
99-
| Approve Change Request | Approving or denying existing Change Requests |
100-
| View Identities | Viewing Identities |
164+
| Permission | Ability |
165+
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
166+
| Administrator | Grants full read and write access to all feature states, overrides, identities and change requests in this environment. |
167+
| View Environment | Allows viewing this environment. The environment is hidden from users without this permission. |
168+
| Update Feature State | Allows updating updating any feature state or values in this environment. |
169+
| Manage Identities | Grants read and write access to identities in this environment. |
170+
| Manage Segment Overrides | Grants write access to segment overrides in this environment. |
171+
| Create Change Request | Allows creating change requests for features in this environment. |
172+
| Approve Change Request | Allows approving or denying change requests in this environment. |
173+
| View Identities | Grants read-only access to identities in this environment. |

‎docs/docusaurus.config.js

+5
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,11 @@ const config = {
1212
onBrokenLinks: 'throw',
1313
onBrokenMarkdownLinks: 'warn',
1414

15+
markdown: {
16+
mermaid: true,
17+
},
18+
themes: ['@docusaurus/theme-mermaid'],
19+
1520
themeConfig:
1621
/** @type {import('@docusaurus/preset-classic').ThemeConfig} */
1722
({

0 commit comments

Comments
 (0)