Subjects, Roles and Permissions
Role-Based Access Control (RBAC)
The witboost product implements the role-based access control model as its authorization model.
With role-based access control, users are assigned to roles and permissions are assigned to roles, creating a decoupling between individuals and their permissions. Some strengths of this approach are:
- Flexibility: RBAC allows for a high degree of flexibility in defining roles and permissions. It is easy to add or remove users from roles, or to modify the permissions associated with a role.
- Efficient resource management: RBAC can help organizations manage their resources more effectively by allowing them to define access controls based on the roles of users, rather than on individual users themselves.
- Improved security: By defining access controls based on roles, organizations can ensure that users only have access to the resources they need to do their jobs, which can help to reduce the risk of unauthorized access to sensitive information.
RBAC Model
The Role-Based access control implementation in witboost is composed of the following entities:
- Subjects: that can be a user or a group of users
- Roles: that is a set of permissions with a logical name (e.g.
Data Product Owner
role) - Permissions: the set of grantable actions available in witboost
The diagram below summarizes the relationships between these entities:
Configuring RBAC
Roles and grants must be configured by accessing the RBAC tables in the database.
RBAC internally stores roles, permissions and grants using 4 tables. Those tables can be found inside the rbac
schema and they are:
permissions
: Stores all known witboost permissions. It is automatically filled up by witboost at the start time. Must be left as it is.roles
: Stores all roles defined by the Platform Teamroles_permissions
: Stores bindings between roles and permissions. Bindings are defined by the Platform Teamroles_subjects
: Stores bindings between subjects and roles. Bindings are defined by the Platform Team, except in some cases where witboost can automatically create them.
A subject is either a user or a group of users.
Make sure to set the full entity ref of a subject including the namespace. e.g group:default/agile_lab
Defining a role
Roles can be defined by inserting rows into the roles
table.
A role is defined by the following fields:
id
: A unique string identifier of the role e.g.DP_OWNER
display_name
(optional): A prettier role identifier or human-readable name for display purposesdescription
(optional): A description of the role, for display purposesvisibility
set to theuser
if this role should be visible in theRbacRolePicker
or if it can be passed to the RBAC Scaffolder Action. set tointernal
otherwise. By default this field is always set tointernal
.
Here is an example SQL query:
INSERT INTO rbac."roles"(id, display_name, description, visibility)
VALUES ("DP_OWNER", "Data Product Owner", "Manages the whole lifecycle of a data product", 'user')
INSERT INTO rbac."roles"(id, display_name, description, visibility)
VALUES ("SUPERADMIN", "Super Admin", "Manages all aspects of the platform", 'internal')
Binding permissions to a role
To make a role useful, it needs to have some permissions associated to it.
Permissions can be bound to a role by inserting rows into the roles_permissions
table.
A role-permission association is defined by the following fields:
role_id
(foreign key): Anid
of an existing role in theroles
tablepermission_id
(foreign key): Anid
of an existing permission in thepermissions
table. See the Permissions section for a detailed overview all available permissions
Here is an example SQL query:
INSERT INTO rbac."roles_permissions"(role_id, permission_id)
VALUES ("DP_OWNER", "catalog.entity.read")
Granting permissions to a subject
Finally, after creating roles and associating some permissions to them, you can associate subjects to roles, i.e. you grant them some permissions.
A grant is an equivalent word for a role-subject or subject-to-role association expression.
A role-subject binding is defined as follows:
subject
: Subject who will be assigned to the role. They are in the formatuser:<namespace>/<username>
orgroup:<namespace>/<groupname>
. See Subjects.role_id
: Role'sid
to be assigned to the subjectentity_ref
(optional): It is the scope (in the form of an entity reference) of the role. Entity reference is required if any permission linked to the role requires a scope. This field must be filled with a valid scope. See Scopes.enabled
: Enable/Disable a grant. If set tofalse
the role-subject association is disabled and won't make any effect on the subject
The id
field of the roles_subjects
table is left out of the presentation and query since it is an auto-increment value.
Be aware that groupname must be the group id of the entity (metadata.name
), and not the name taken from LDAP/Active Directory (usually it is all lowercase with no spaces, but that can contain underscores). To see what is the group id to be used, you can check the group details in the Software Catalog
page, by extracting the metadata.name
field of the group.
Example
A group with the name Finance Admin Data Product
is not stored in that way in the database, since it contains spaces and has capital letters. By default, the normalization converts it to finance_admin_data_product
.
Here is an example SQL query:
INSERT INTO rbac."role_subject"(subject, role_id, entity_ref, enabled)
VALUES ("user:default/john.doe_agilelab.it", "user", "DP_OWNER", "urn:dmb:dp:finance:customer-invoice:1", true)
Subjects
A subject is a person or a system that is requesting access to a resource. The subject is authenticated by witboost and is assigned to a set of roles that determine what actions the subject is authorized to perform.
A subject in witboost is defined by the subject
field in the roles_subjects
table.
Subjects in witboost, i.e. the subject
field must comply to one of the two possible formats:
- Groups: identified by
group:<namespace>/<subject_name>
(e.g.user:default/john.doe_agilelab.it
) - User: identified by
user:<namespace>/<subject_name>
(e.g.group:default/agilers
)
Where:
<namespace>
: identifies the namespace of users and groups. In witboost, it defaults todefault
<subject_name>
is the username or group name of the subject.
Scopes
The scope of permission refers to the specific resources or functions to which the permission applies. In other words, it defines the specific areas of witboost where the permission can be exercised (e.g. User can read only Data Products within the Finance domain).
Permission can require a scope, and the set of permissions assigned to a defined role will be usually a mix of permissions that require a scope and others that don't require any scope.
In witboost, you can assign one of the following types of scopes to a role-subject definition, using the entity_ref
field:
- Domain URN scope: a URN representation of a domain entity in the format
urn:dmb:dmn:<domain name>
- Data Product URN scope: a URN representation of a data product entity in the format
urn:dmb:dp:<domain name>:<data product name>:<version>
- Resource URN scope: a URN representation of a resource entity in the format
urn:dmb:rsr:<domain name>:<resource name>
entity_ref
is a URN value: as such in Witboost is treated as a case-insensitive value.
For example, the values urn:dmb:dmn:Finance
and urn:dmb:dmn:finance
are treated as equal.
Those scopes will be indicated as Catalog Entity URN in the tables that you will find below on this page.
Scopes have a hierarchy between each other. For instance: a user assigned to a role with scope urn:dmb:dmn:finance
can exercise his/her role to the whole Finance domain and the corresponding Data Products contained in it.
This is an overview of the scopes hierarchy, each node of the graph indicates that if you assign a user the scope in a node, they will be also authorized to exercise his/her role on the children nodes (i.e. scopes):
An example:
-
A user has role
Domain Owner
with permissions:catalog.entity.read
,catalog.entity.create
,catalog.location.read
,catalog.location.create
,catalog.entity.refresh
and scope:urn:dmb:dmn:finance
-
This user can: read all data products, resources, releases, and components under the Finance domain in the Builder module. Create a data product or a component or register an existing one in the Builder module, still under the Finance domain.
-
This user cannot: create a new version of a data product, or use the test, release, or deployment features of any data product even if those data products are under the Finance domain.
If you want to restrict the visibility of a Template or a Blueprint to users of a specific domain, just place a reference to the domain inside spec.domain
property.
Take as an example the blueprint's descriptor below:
apiVersion: agilelab.it/v1alpha1
kind: Blueprint
metadata:
name: test-blueprint
title: Test Blueprint
description: Create a Test Blueprint
tags:
- test
spec:
lifecycle: experimental
owner: group:test
domain: domain:finance
# ...other properties...
Permissions
In the context of Role-Based Access Control (RBAC), permission is a specific action or set of actions that a user or group is authorized to perform within a system.
For example, permission might allow a user to read a list of data products, execute certain commands on them, or access certain resources in witboost.
Permissions are typically granted to users or groups through the assignment of roles, which are defined collections of permissions that are assigned to users or groups to control their access to system resources and functions.
Below we dive into each witboost module and understand which are all the available permissions. You will also find some cookbooks that facilitate the definition of permissions based on use cases.
Practice Shaper
Learn about the Practice Shaper in the dedicated section of the documentation.
Permission | Description | Scope |
---|---|---|
practice-shaper.edit | Gives access to the Practice Shaper settings in the Platform Settings page (see platform.settings.edit permissions below) | none |
practice-shaper.import | Gives access to the Practice Shaper import. The "Register new entity" button will show. | none |
Catalog Module
The catalog is the core module in witboost. It keeps track of all entities you work with in witboost (e.g. data products, components, resources, users, groups, domains and templates). Thus, most of witboost modules and core components interact with the catalog (e.g. Builder, Scaffolder, etc.), meaning that some actions that we take on those dependent modules (e.g. making a commit on a data product from the Builder module), will require the user to have permissions both for the dependent module (e.g. the Builder) and the Catalog module. So in this sense, catalog permissions are needed for most operations behind the scenes.
The catalog works with two objects:
- Entities: these are data products, components, resources, users, groups, domains and templates. But not Governance policies or Marketplace items
- Locations: there are the URLs or paths to the
catalog-info.yaml
that generate the corresponding entity. e.g. for a data product, the location corresponds to the URL that points to thecatalog-info.yaml
in the data product's repository. The catalog will periodically process each location and regenerate all entities so that they stay up-to-date with what is found from the origin location.
The actions that a user can take on the catalog are:
- Read/Add/Delete/Refresh entities in the catalog
- Read/Add/Delete locations in the catalog
Adding locations and adding entities might be misleading or confuse the user. When you create a data product or an output port from a template, you are creating a repository and then adding the location of that repository in the catalog. Then the catalog will process the new location and will generate the corresponding entity from the catalog-info.yaml
.
What you see in the software catalog is the list of entities that have been already processed. This is why sometimes the entity that you just created is not yet visible in the catalog because its location has not been already processed.
Catalog Permissions
In this section, we will describe what permissions are present in the catalog module. These permissions can be assigned to roles defined by the platform team.
Permission | Description | Scope |
---|---|---|
catalog.entity.read | Authorizes reading one or more entities from the catalog. | Catalog Entity URN |
catalog.entity.create | Authorizes creating new catalog projects (system or component). This includes registering existing systems/components from the related button. | none |
catalog.entity.delete | Authorizes removing systems/components from the platform. This enables the "Unregister Entity" button. | Catalog Entity URN |
catalog.entity.refresh | Authorizes refreshing systems/components. This enables the refresh button on the detail pages. | Catalog Entity URN |
catalog.location.create | Authorizes the registration of one or more locations from the catalog. This is needed when registering an existing component into the catalog or scaffolding a new one. | none |
catalog.location.read | Authorizes reading one or more location from the catalog. | none |
catalog.location.delete | Authorizes deleting locations from the catalog. | none |
catalog.platform.create | Authorizes creating new entities. This enables any entity to be registered, and not only project ones. This permission also requires the catalog.entity.create permission to be enabled. Moreover, this permission enables the Template Editor link. | none |
catalog.platform.delete | Authorizes removing entities (unregistration). This enables any entity to be unregistered, and not only project ones. This permission also requires the catalog.entity.delete permission to be enabled. | none |
catalog.platform.refresh | Authorizes refreshing entities. This enables any entity to be refreshed, and not only project ones. This permission also requires the catalog.entity.refresh permission to be enabled. | none |
builder.software-catalog.view | Authorizes the user to see the "Software Catalog" page. | none |
You will likely have roles that will mix catalog permissions with builder permissions, thus refer to the Builder Module section below to clarify which permissions are needed in the day-to-day workflows in witboost.
Builder Module
The main operations that a user can perform on the Builder module are:
- Create a data product/component using a template
- Create a new data product version
- Register an existing data product/component
- View the software catalog/data products and their details
- Build and deploy: test policies, create a draft release, update/promote the release, deploy/undeploy a release
Builder Permissions
In this section, we will describe what permissions are present in the Builder module. These permissions can be assigned to roles defined by the platform team.
Permission | Description | Scope |
---|---|---|
builder.dp.snapshot.create | Authorizes the creation of a new release entity with version x.y.z-SNAPSHOT | Catalog Entity URN |
builder.dp.release | Authorizes the release of an entity's release. | Catalog Entity URN |
builder.dp.deploy.{env} | Authorizes deploy action on a dataproduct. You can specify a permission for each environment. | Catalog Entity URN |
builder.dp.newversion | Authorizes cloning of a dataproduct with a major version increment | Catalog Entity URN |
builder.dp.commit | Authorizes updating the release entity and increase the minor version. | Catalog Entity URN |
builder.dp.policies.test | Authorizes testing policies on a dataproduct | Catalog Entity URN |
As you can notice, there is no 1 to 1 mapping between the main operations described and the permissions available in this table. This is because each operation most of the time involves more than one permission to be authorized.
Builder Permissions Cookbook - General
This cookbook can be used by the Platform team as a reference when configuring RBAC. For each action listed in the table, there will be a list of permissions needed. This table will indicate if the action also requires a scope. If you are in doubt about which scope to set, read the Scopes section above.
Action | Description | Permissions Needed | Requires Scope? |
---|---|---|---|
Use a template (e.g. Create a data product/component) | Create a Data Product/component by using a template | catalog.entity.read , catalog.location.create , catalog.entity.refresh | Yes |
Register an existing Data Product/Component/Template | Register an existing Data Product/Component/Template by using the Builder > Register Existing Component feature | catalog.entity.create , catalog.location.create | No |
View data products/components and their details | See a list of available entities in witboost (e.g. data products) and access their details | catalog.entity.read , catalog.location.read | Yes |
View templates list | View the list of registered templates in witboost | none | No |
Triggering an entity refresh | Refresh an entity by clicking on the refresh button in the About card of any data product or component | catalog.entity.refresh | Yes |
View the software catalog in builder section | View the software catalog in builder section | builder.software-catalog.view | No |
Builder Permissions Cookbook - Release Management
User must be already authorized to view the data product and hence, the Edit and Test
and Deployment
tabs. The required permissions described below will still list permissions needed as if the user is not already authorized to view the data product.
Action | Description | Permissions Needed | Requires Scope? |
---|---|---|---|
Create New Draft Release | Create a new draft release for a data product | catalog.entity.read , catalog.entity.refresh , catalog.location.create , builder.dp.snapshot.create | Yes |
Promote a Draft Release | Promotes a draft release into a release | catalog.entity.read , catalog.entity.refresh , builder.dp.release | Yes |
View all Data Product's releases | View the list of releases for a data product | It is implicitly granted when a user can view a Data Product | N/A |
Create a new Data Product version | Create a new Data Product version that is a clone of the existing one | catalog.entity.read , catalog.location.create , builder.dp.newversion | Yes |
Update a Draft Release | Commits latest changes by updating the draft release | catalog.entity.read , catalog.entity.refresh , builder.dp.commit | Yes |
Get a preview descriptor | Get preview descriptor of a Data Product | catalog.entity.read , catalog.entity.refresh | Yes |
Test policies compliance | Test if a data product is compliant with governance policies | catalog.entity.read , catalog.entity.refresh , builder.dp.policies.test | Yes |
Deploy/Undeploy a data product | Deploy/Undeploy a data product's release to a specific environment | catalog.entity.read , catalog.entity.refresh ,builder.dp.deploy.{env} | Yes |
Computational Governance Platform Module
The main operations that a user can perform on the CGP (Computational Governance Platform) module are:
- View governance policies/metrics
- Create governance policies/metrics
- Delete governance policies/metrics
- Edit governance policies/metrics
Computational Governance Platform permissions
In this section, we will describe what permissions are present in the Cgp module. These permissions can be assigned to roles defined by the platform team.
Permission | Description | Scope |
---|---|---|
cgp.entity.edit | Authorizes the view/creation/editing/deletion/testing and change status of a policy/metric. Moreover, Flags column in marketplace is visible and Flag and Score dialog is accessible. | none |
cgp.entity.view | Authorizes the view of a policy/metric. Moreover, Flags column in marketplace is visible and Flag and Score dialog is accessible. | none |
Marketplace Module
The main operations that a user can perform on the Marketplace module are:
- View the Marketplace Search page with all data products/output ports and their details
- View the Marketplace Visual Discovery
- Access Mesh Supervision
- Send an access request to a Data Product's output port
- Give access to a Data Product's output port
- Write a review on a Data Product
- Ask questions on a Data Product
- Answer questions on a Data Product
At the moment all operations described above are, by default, granted to any user of witboost. The only exception is made by those who can give access to a Data Product's output port or who can answer a question, that is safe by design since only the Data Product owner will receive the request, and hence is the only one that can answer to that.
Other Platform permissions
All other useful platform permissions can be found in this section. These permissions can be assigned to roles defined by the platform team.
Permission | Description | Scope |
---|---|---|
platform.settings.edit | Authorizes the view/use of the platform settings page. Who can view the settings page can also edit them, there is no distinction yet. | none |
documents.document.insert | Authorizes the insertion of a document into the database through its respective route. Refer to the documents documentation page for more information. | none |
platform.custom-view.edit | Can see and use the download button for Custom Views, and use the REST API to add a new custom view. | none |