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.

tip

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.

tip

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 from spec.mesh.dataProductOwner of the catalog-info.yaml, internally RBAC will adjust user:test.user_agilelab.it into a slightly different format: user:default/test.user_agilelab.it that includes the namespace
• role_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 logs
• entity_ref field is filled with the value taken from metadata.name of the catalog-info.yaml. the value found will be converted in a URN.

caution

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 be system (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 the subjectField. This role must exist in the roles database table.
  • entityRefField: Specifies a field inside the entity from which the scope will be extracted. It means that the user assigned to the roleId 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 in entityRefField must be convertible to a witboost URN.

tip

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'