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 Team
• roles_permissions: Stores bindings between roles and permissions. Bindings are defined by the Platform Team
• roles_subjects: Stores bindings between subjects and roles. Bindings are defined by the Platform Team, except in some cases where Witboost can automatically create them.

note

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. Example: group:default/agile_lab. See the Subjects section for more details.

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 purposes
• description (optional): A description of the role, for display purposes
• visibility: Set to user if this role should be visible in the RbacRolePicker or if it can be passed to the RBAC Scaffolder Action. Set to internal otherwise. By default this field is always set to internal.

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 ('ADMINISTRATOR', 'Administrator', '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): An id of an existing role in the roles table
• permission_id (foreign key): An id of an existing permission in the permissions 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.

note

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 format user:<namespace>/<username> or group:<namespace>/<groupname>. See Subjects.
• role_id: Role's id to be assigned to the subject
• entity_ref (optional): Defines the scope (in the form of an entity reference) of the role. An entity reference is required if any permission linked to the role requires a scope. For these cases, this field must be filled with a valid scope. See Scopes.
• enabled: Enable/Disable a grant. If set to false the role-subject association is disabled and won't make any effect on the subject

note

The id field of the roles_subjects table is left out of the presentation and query since it is an auto-increment value.

Here is an example SQL query:

INSERT INTO rbac."roles_subjects"(subject, role_id, entity_ref, enabled)
VALUES ('user:default/john.doe_agilelab.it', '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 in the tables, must comply to one of the two possible formats:

• Groups: identified by group:<namespace>/<subject_name> (e.g. group:default/agile_lab)
• User: identified by user:<namespace>/<subject_name> (e.g. user:default/john.doe_agilelab.it)

Where:

• <namespace>: identifies the namespace of users and groups. In Witboost, it defaults to default; you can verify it by inspecting the entity (group or user) via the Software Catalog, and checking the metadata.namespace field.
• <subject_name> is the username or group name of the subject:
  • For a group it usually is the normalized group name; ie for a group "Agile Lab", the subject name is agile_lab (note the lowercasing and the space being replaced by _). It can be verified through the Software Catalog, checking the metadata.name field.
  • For a user it usually is the normalized email address; ie for a user with email "john.doe@agilelab.it", the subject name is john.doe_agilelab.it (note the @ being replaced with _). It can be verified through the Software Catalog, checking the metadata.name field.

caution

If you are not sure what the namespace or normalized id is for a user or group, check it using the Software Catalog, as otherwise it can be difficult to debug permission problems.

Go to "Software Catalog", select either "User" or "Group" as kind, and select the entity you are interested in:

Then use the three button menu to inspect the raw entity:

Then use the "Inspect Raw YAML" and look at the metadata.namespace and metadata.name fields:

Scopes

The scope of a 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 systems 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:

• Global scope: Setting the entity_ref to the asterisk wildcard * will grant the permission on the whole set of catalog entities
• Domain URN scope: a URN representation of a domain entity in the format urn:dmb:dmn:<domain name>
• System URN scope: a URN representation of a system (like a data product) entity in the format urn:dmb:dp:<domain name>:<system name>:<version>
• Resource URN scope: a URN representation of a resource entity in the format urn:dmb:rsr:<domain name>:<resource name>

note

Non-wildcard entity_ref values are URNs: On Witboost these are treated as case-insensitive values. 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 Systems 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 systems, resources, releases, and components under the Finance domain in the Builder module. Create a system (like 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 system, or use the test, release, or deployment features of any system even if those systems are under the Finance domain.

tip

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), a permission is a specific action or set of actions that a user or group (via a role) is authorized to perform within a system.

For example, a permission might allow a user to read a list of systems, 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 then 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. systems, 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 systems, 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 the catalog-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

note

Adding locations and adding entities might be misleading or confuse the user. When you create a system 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 entities (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

tip

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 system/component using a template, e.g. a data product
• Create a new system version
• Register an existing system/component
• View the software catalog/project tab 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 system. You can specify a permission for each environment.	Catalog Entity URN
builder.dp.newversion	Authorizes cloning of a system 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 system	Catalog Entity URN

note

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 project/component)	Create a project/component by using a template	catalog.entity.read, catalog.location.create, catalog.entity.refresh	Yes
Register an existing project/Component/Template	Register an existing project/Component/Template by using the Builder > Register Existing Component feature	catalog.entity.create, catalog.location.create	No
View systems/components and their details	See a list of available entities in Witboost (e.g. a data product) and access their details	catalog.entity.read, catalog.location.read	Yes
View templates list	View the list of registered templates in Witboost	catalog.entity.create	No
Triggering an entity refresh	Refresh an entity by clicking on the refresh button in the About card of any project 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 project 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 project.

Action	Description	Permissions Needed	Requires Scope?
Create New Draft Release	Create a new draft release for a project	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 project's releases	View the list of releases for a project	It is implicitly granted when a user can view a project	N/A
Create a new project version	Create a new project 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 project	catalog.entity.read, catalog.entity.refresh	Yes
Test policies compliance	Test if a project is compliant with governance policies	catalog.entity.read, catalog.entity.refresh, builder.dp.policies.test	Yes
Deploy/Undeploy a project	Deploy/Undeploy a project'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 systems/output ports and their details
• View the Marketplace Visual Discovery
• Access Mesh Supervision
• Send an access request to a project's output port
• Give access to a project's output port
• Write a review on a project
• Ask questions on a project
• Answer questions on a project

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 project's output port or who can answer a question, that is safe by design since only the project owner will receive the request, and hence is the only one that can answer to that.

RBAC

In this section we will describe what permissions are present in the RBAC plugin of the platform. These permissions can be assigned to roles defined by the platform.

caution

These permission relate to the authorization system of Witboost, enabling adding or removing roles assignments as well as roles permissions. Assign these permissions only to highly-privileged roles like Administrator.

Permission	Description	Scope
rbac.role.create	Create new roles without roles permissions or roles subjects.	none
rbac.role.delete	Delete user roles.	none
rbac.role.edit	Update existing roles and assigning roles permissions or roles subjects. Disabling of Authenticated Guest Users.	none

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
platform.extension-manager.edit	Can use the extension manager REST API to perform edit operations. Can access the extension manager admin section.	none