d5fbd0b743
## What This (admittedly massive) PR updates the "physical" documentation structure and fixes url inconsistencies and SEO problems reported by marketing. The main points are: - remove or move directories : advanced, user_guide, deploy, api - move the files contained within to the appropriate one of topics, how-to, tutorials, or reference - update internal doc links and product links to the content - create client-side redirects for all the urls that have changed. A number of the files have been renamed in small ways to better match their url and to make them easier to find. Additionally, the top-level api directory has been moved to /reference/api/legacy/unleash (see the discussion points section for more on this). ## Why When moving our doc structure to diataxis a while back, we left the "physical' files lying where they were, because it didn't matter much to the new structure. However, that did introduce some inconsistencies with where you place docs and how we organize them. There's also the discrepancies in whether urls us underscores or hyphens (which isn't necessarily the same as their file name), which has been annoying me for a while, but now has also been raised by marketing as an issue in terms of SEO. ## Discussion points The old, hand-written API docs have been moved from /api to /reference/api/legacy/unleash. There _is_ a /reference/api/unleash directory, but this is being populated by the OpenAPI plugin, and mixing those could only cause trouble. However, I'm unsure about putting /legacy/ in the title, because the API isn't legacy, the docs are. Maybe we could use another path? Like /old-docs/ or something? I'd appreciate some input on this.
8.4 KiB
| id | title |
|---|---|
| rbac | Role-based Access control |
This document forms the specifications for Role-Based Access Control which was introduced as part of the Unleash v4 release.
Core principles
Unleash has two levels in its hierarchy of resources:
- Global resources - Everything that lives across the entire Unleash instance. Examples of this include:
- activation strategies
- context field definitions
- addon configurations
- applications
- users
- Project resources - Resources which are only available under a project. Today this is only “feature toggles” (but we expect more resources to live under a project in the future). A feature toggle will belong to only one single project. In Unleash-Open source there exists only a single project, the “default” project, while Unleash Enterprise supports multiple projects.
Unleash v4 allows you control access to both global resources and individual project resources.
Standard 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.
When you add a new user, you can assign them one of the global 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 |
| 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 Project Roles
:::info availability
Custom project roles were introduced in Unleash 4.6 and are only available in Unleash Enterprise.
:::
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.
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)
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.
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.
User Groups
:::info availability
User groups are available to Unleash Enterprise users since Unleash 4.14.
:::
User groups allow you to assign roles to a group of users within a project, rather than to a user directly. This allows you to manage your user permissions more easily when there's lots of users in the system. For a guide on how to create and manage user groups see how to create and manage user groups.
A user group consists of the following:
- a name (required)
- a description (optional)
- a list of users (optional)
- a list of SSO groups to sync from (optional)
Groups do nothing on their own. They must be given a role on a project to assign permissions. You can assign both standard roles and custom project roles to groups.
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 to a project through more than one group, the user will inherit most permissive permissions of all their groups in that project.
User Group SSO Integration
:::info availability
User group syncing is planned to be released in Unleash 4.18 and will be available for enterprise customers.
:::
User groups also support integration with your Single Sign-On (SSO) provider. This allows you to automatically assign users to groups when they log in through SSO. Check out how to set up group SSO sync for a step-by-step walkthrough.
Users that have been added to a group through your SSO provider will be automatically removed next time they log in if they've been removed from the SSO group. Users that have been manually added to the group will not be affected.
To enable group sync, you'll need to set two fields in your SSO provider configuration options:
-
enable group syncing:
Turns on group syncing. This is disabled by default.
-
group field JSON path
A JSON path that should point to the groups field in your token response. This should match the exact field returned by the provider. For example, if your token looks like this:
{ "iss": "https://some-url.com", "azp": "1234987819200.apps.some-url.com", "aud": "1234987819200.apps.some-url.com", "sub": "10769150350006150715113082367", "at_hash": "HK6E_P6Dh8Y93mRNtsDB1Q", "hd": "example.com", "email": "jsmith@example.com", "email_verified": "true", "groups": ["test-group", "test-group-2"], //the field where groups are specified "iat": 1353601026, "exp": 1353604926, "nonce": "0394852-3190485-2490358" }You need to set the "Group Field JSON path" to "groups".
Once you've enabled group syncing and set an appropriate path, you'll need to add the SSO group names to the Unleash group. This can be done by navigating to the Unleash group you want to enable sync for and adding the SSO group names to the "SSO group ID/name" property.