Grant Mechanisms
To improve Platform team experience, witboost automatically grants some permissions to users under certain rules and certain events (e.g. data product creation, domain creation, etc.).
A Grant Mechanism rule, can be as an example one which, when a new data product is created, gives some catalog permissions to the data product owner, so that can start working on it.
Grant Mechanisms can be configured through app-config
. Refer to the Configuration to know how to configure them.
It is recommended to configure a Grant Mechanism to allow the data product owner to use her/his new data product.
Triggering a Grant Mechanism
At the core of this functionality, we can find the Permission Processor. This component is installed in the catalog plugin and at startup time, will load all defined Grant Mechanisms.
At each catalog refresh cycle, the Permission Processor will call each of the Grant Mechanisms together with the current entity being refreshed. Each Grant Mechanism will generate a set of role_subject
entities. Each of them will be added to the roles_subjects
table if the association does not already exist.
Thus, Grant mechanisms are fired when:
- Adding a new entity into witboost's catalog
- Refreshing an entity in the witboost's catalog (done periodically by the catalog)
But a Grant Mechanism only executes its logic if the entity kind matches the one specified inside the configuration, otherwise, it is skipped.
If permissions are disabled or there is no configured Grant Mechanism, the Permission Processor will not be creating any overhead to the catalog refresh cycle.
Configuring Grant Mechanisms
This is an example configuration of a default granting mechanism
permission:
enabled: true
defaultGrants:
- kind: 'System'
entityGrantRules:
- subjectField: spec.mesh.dataProductOwner
roleId: DP_OWNER
entityRefField: metadata.name
These lines instruct witboost to create a default granting mechanism for entities of kind System
. It will assign a DP_OWNER
role to the user found in the spec.mesh.dataProductOwner
field with the metadata.name
value as scope.
As an example, consider this catalog-info.yaml
of a System entity:
{
apiVersion: 'backstage.io/v1alpha1',
kind: 'System',
metadata:
{
namespace: 'default',
annotations: {},
name: 'marketing.end-to-end-test-dp.1',
},
spec:
{
type: 'dataproduct',
lifecycle: 'experimental',
owner: 'group:datameshplatform',
domain: 'domain:marketing',
mesh:
{
name: 'End to End test DP',
version: '1.6.0',
dataProductOwner: 'user:test.user_agilelab.it',
},
},
}
Given the default grant above, witboost will register a new grant in the roles_subjects
table because the entity kind
matches the kind
handled by our configured grant mechanism. Thus, in the end, a new row will appear in the roles_subjects
table:
id | subject | role_id | entity_ref | enabled |
---|---|---|---|---|
234 | user:default/test.user_agilelab.it | CATALOG_BASIC_USER | urn:dmb:dp:marketing:end-to-end-test-dp:1 | true |
This new row is the result of the Grant Mechanism reading data from the input catalog-info.yaml
received in the processor, during a catalog refresh cycle:
subject
field is filled with the value taken fromspec.mesh.dataProductOwner
of thecatalog-info.yaml
, internally RBAC will adjustuser:test.user_agilelab.it
into a slightly different format:user:default/test.user_agilelab.it
that includes the namespacerole_id
is taken directly from the Grant Rule configuration, if the role does not exist on the database an error will be thrown and will be visible in the application logsentity_ref
field is filled with the value taken frommetadata.name
of thecatalog-info.yaml
. the value found will be converted in a URN.
If no grant mechanism is configured, then by default witboost won't create user permissions on entity creation. This can create cases in which the user is not allowed to view or access her own entity.
Grant Mechanism Template
The general structure of the defaultGrants
configuration is as follows:
permission:
enabled: true
defaultGrants: <array>
- kind: <string>
entityGrantRules: <array>
- subjectField: <string>
roleId: <string>
entityRefField: <string>
// ... more rules stay here ...
// ... more default grants stay here ...
defaultGrants
is an array of grant mechanisms, potentially one for each kind.
Each grant mechanism is then defined by the following fields:
kind
: can besystem
(for a data product),domain
,template
,component
. Each grant mechanism's logic only gets executed if the catalog is processing an entity whose kind matches the value of this field.entityGrantRules
is the array of rules to be executed when the grant mechanism logic gets executed:subjectField
: Specifies a field inside the entity from which the subject (i.e. the granted user) will be taken. Must be a valid entity field.roleId
: It is the role that will be assigned to the subject extracted from thesubjectField
. This role must exist in theroles
database table.entityRefField
: Specifies a field inside the entity from which the scope will be extracted. It means that the user assigned to theroleId
will be authorized only for the extracted entity name or id. This field is always mandatory, meaning that you cannot create a role without scope using Grant Mechanisms. The value contained inentityRefField
must be convertible to a witboost URN.
Fields specified in Grant Mechanisms configurations also support an array of values found in a specified field like below:
spec:
mesh:
name: 'IT'
dataProductOwner:
- 'group:bigdata'
- 'group:dev'
- 'group:datamesh'