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. 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 purposes
• description (optional): A description of the role, for display purposes
• visibility set to the 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 ("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): 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): 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 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.

caution

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 to default
• <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>

note

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.

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), 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 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 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

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 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

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 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 catalog with all data products/output ports and their details
• View the Marketplace graph
• 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