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. 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 purposesdescription
(optional): A description of the role, for display purposesvisibility
: Set touser
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 ('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): 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): 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 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.
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 todefault
; you can verify it by inspecting the entity (group or user) via the Software Catalog, and checking themetadata.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 themetadata.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 themetadata.name
field.
- For a group it usually is the normalized group name; ie for a group "Agile Lab", the subject name is
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>
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.
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...