Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Deprecate group-level permissions. Rewrite RBAC docs and add Mermaid diagrams #4469

Merged
merged 6 commits into from
Aug 13, 2024
Merged

docs: Deprecate group-level permissions. Rewrite RBAC docs and add Mermaid diagrams #4469

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
185e237
Rewrite RBAC docs, add Mermaid diagrams
rolodato Aug 9, 2024
19f9829
Fix broken links
rolodato Aug 9, 2024
5415272
prettier bad
rolodato Aug 9, 2024
ec6a1a4
Improve permissions reference section
rolodato Aug 12, 2024
d17b081
Add deprecation warning to groups permissions
rolodato Aug 12, 2024
3987737
Update version for deprecated group permissions
rolodato Aug 13, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
195 changes: 134 additions & 61 deletions docs/docs/system-administration/rbac.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,100 +1,173 @@
---
title: Role Based Access Control
title: Role-based access control
---

Flagsmith provides fine-grained permissions to help larger teams manage access and roles across organisations, projects
and environments.

:::info

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

:::

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

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

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

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

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

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

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

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

### Roles

A _Role_ is an entity to which you can attach a set of permissions. Permissions can allow privileges at Organization,
Project, and Environment levels. You can assign a role, along with its associated permissions, to a User or Group. You
will also be able to assign API keys to a Role in future versions.
A role is a set of permissions that, when assigned, allows performing specific actions on your organisation, projects or
project environments.

**Built-in roles** are predefined by Flagsmith and cannot be modified. All users in your organisation have one of the
following built-in roles:

- _Organisation Administrator_ grants full access to everything in your Flagsmith organisation.
- _User_ grants no access and requires you to assign permissions using custom roles and/or groups.

**Custom roles** can be assigned to users, groups or [Admin API](/clients/rest/#private-admin-api-endpoints) keys. Any
number of custom roles can be created and assigned.

Creating, modifying or assigning roles requires organisation administrator permissions.

### Groups

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
group members. Users can belong to any number of groups.

Creating or modifying existing groups requires organisation administrator permissions.

Permissions to add or remove users from groups can be granted in two ways:

- The _manage group membership_ permission allows modifying any group's membership
- A _group admin_ can manage membership only for that group

## Add users to your organisation

You can add users to your organisation by sending them an invitation email from Flagsmith, or by sharing an invitation
link directly with them. Both options require organisation administrator permissions, and are available from **Users and
Permissions > Members**.

Users can also join your organisation directly by logging in to Flagsmith using
[single sign-on](/system-administration/authentication/SAML/).

### Email invites

:::info

If you are self-hosting Flagsmith, you must
[configure an email provider](/deployment/hosting/locally-api#email-environment-variables) before using email invites.

:::

To send invitation emails to specific users, click on **Invite members**. Then, fill in the email address and built-in
role of each user you want to invite.

When a user accepts their email invitation, they will be prompted to sign up for a Flagsmith account, or they can choose
to log in if they already have an account with the same email address.

Users who have not yet accepted their invitations are listed in the "Pending invites" section at the bottom of this
page. From here you can also resend or revoke any pending invitations.

### Invitation links

:::warning

Anyone with an invitation link can join your Flagsmith organisation at any time. Share these links with caution and
regenerate them if they are compromised.

:::

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

You can create a Role in the Organisation Settings page.
## Provision permissions

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

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

**E.g. Add Project permission:**
## Deprecated features

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

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

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

**E.g. Assign role to a user:**
## Permissions reference

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

## Permissions
### User group

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

### Organisation

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

### Project

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

### Environment

| **Permission** | **Ability** |
| ------------------------ | --------------------------------------------------------------- |
| Administrator | Can modify Feature Flag, Remote Config and Segment values |
| View Environment | Can see the Environment within their account |
| Update Feature State | Update the state or value for a given feature |
| Manage Identities | View and update Identities |
| Manage Segment Overrides | Permission to manage segment overrides in the given environment |
| Create Change Request | Creating a new Change Request |
| Approve Change Request | Approving or denying existing Change Requests |
| View Identities | Viewing Identities |
| Permission | Ability |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| Administrator | Grants full read and write access to all feature states, overrides, identities and change requests in this environment. |
| View Environment | Allows viewing this environment. The environment is hidden from users without this permission. |
| Update Feature State | Allows updating updating any feature state or values in this environment. |
| Manage Identities | Grants read and write access to identities in this environment. |
| Manage Segment Overrides | Grants write access to segment overrides in this environment. |
| Create Change Request | Allows creating change requests for features in this environment. |
| Approve Change Request | Allows approving or denying change requests in this environment. |
| View Identities | Grants read-only access to identities in this environment. |
5 changes: 5 additions & 0 deletions docs/docusaurus.config.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,11 @@ const config = {
onBrokenLinks: 'throw',
onBrokenMarkdownLinks: 'warn',

markdown: {
mermaid: true,
},
themes: ['@docusaurus/theme-mermaid'],

themeConfig:
/** @type {import('@docusaurus/preset-classic').ThemeConfig} */
({
Expand Down
Loading
Loading