Configuring permissions

In a new implementation of Valtimo no permissions are configured by default. ROLE_ADMIN always has access to the admin menu in order to allow primary setup. Access Control permissions can be configured by defining PERMISSIONS for each ROLE.

This page requires:

• Knowledge of JSON

There are different ways of configuring Permissions in Valtimo.

• Upload a valid permissions JSON via the UI

• Edit permissions directly via the UI

• Place a valid permissions JSON in the codebase via an IDE

Creating permissions

Via UI

Creating permissions is done for a specific role. Assuming a role is present, clicking on that role in the Access control interface opens the permission editor for that role.

configuring-permissions-example

The editor has three tabs:

• Editor — a visual, form-based editor for the role's permissions (shown by default).

• Summary — a read-only, human-readable overview of everything the role is allowed to do.

• JSON editor — the raw permissions JSON, with validation and autocomplete.

Changes are only persisted when you press Save. Because the editor always shows the full list of permissions for the role, removing a permission and saving also removes it in Valtimo.

The visual editor

The Editor tab lists the role's permissions in a sidebar; use New permission to add one. Selecting a permission opens its form, split into three sections:

• Resource & actions — choose the resource type the permission applies to and tick the allowed actions (view, create, modify, delete, …). Only the resource types and actions the system supports are offered.

• Conditions — optionally restrict the permission with one or more conditions: a field (compare a property of the resource), a JSON field (read a value at a JSON path inside the resource's JSON content), or a related resource (evaluate nested conditions on a linked resource — see container conditions). Access is granted only when all conditions are met.

• Context — control whether the permission depends on the context it is evaluated in: no restriction, only when there is no context, or restricted to a specific context resource.

Permission structure

There are a lot of elements that can be specified for permissions. As an example, someone with ROLE_USER can have access to cases of type example-document-definition, or if that someone has been assigned to the case. The following two permissions are used to define this:

[
  {
    "resourceType": "com.ritense.document.domain.impl.JsonSchemaDocument",
    "action": "view_list",
    "conditions": [
      {
        "type": "field",
        "field": "documentDefinitionId.name",
        "operator": "==",
        "value": "example-document-definition"
      }
    ]
  },
  {
    "resourceType": "com.ritense.document.domain.impl.JsonSchemaDocument",
    "action": "view_list",
    "conditions": [
      {
        "type": "field",
        "field": "assigneeId",
        "operator": "==",
        "value": "${currentUsername}"
      }
    ]
  }
]

Going over each element:

• resourceType is required to specify what resource type this permission applies to. For information on the resource types Valtimo provides out of the box, see the configurable elements documentation. For information on how to register custom resource types, see the registering a resource documentation.

• actionKey specifies the kind of action that is being done. In this case, viewing a list. For a list of actions, see the configurable elements documentation.

• conditions is a list describing all the conditions that apply to this particular permission. This requires knowledge of the code for the resource type, as fields can be specified in here correspond to fields inside the class. For information on the kinds of conditions that can be specified, as well as the fields, see this page. Permission is only granted when all conditions for that permission are met.

Via IDE

The example below defines 2 permissions:

• A user with ROLE_ADMIN can VIEW any document

• A user with ROLE_USER can VIEW documents where:

  • the name of the document-definition equals loans

  • the height of the loan is less than 20000

document.permission.json:

{
    "changesetId": "pbac-documents",
    "permissions": [
        {
            "resourceType": "com.ritense.document.domain.impl.JsonSchemaDocument",
            "action": "view",
            "roleKey": "ROLE_ADMIN"
        },
        {
            "resourceType": "com.ritense.document.domain.impl.JsonSchemaDocument",
            "action": "view_list",
            "roleKey": "ROLE_USER",
            "conditions": [
                {
                    "type": "expression",
                    "field": "content.content",
                    "path": "$.height",
                    "operator": "<",
                    "value": 20000,
                    "clazz": "java.lang.Integer"
                },
                {
                    "type": "field",
                    "field": "documentDefinitionId.name",
                    "operator": "==",
                    "value": "loans"
                }
            ]
        }
    ]
}

Joining entities using a container

The example below shows how container conditions can be used to join other entities. In this case, the permission is defined:

• A user with ROLE_USER can VIEW notes where

  • the related document-definition name equals loans

  • the related document is assigned to the current user

note.permission.json:

{
    "changesetId": "pbac-notes",
    "permissions": [
        {
            "resourceType": "com.ritense.note.domain.Note",
            "action": "view",
            "roleKey": "ROLE_USER",
            "conditions": [
                {
                    "type": "container",
                    "resourceType": "com.ritense.document.domain.impl.JsonSchemaDocument",
                    "conditions": [
                        {
                            "type": "field",
                            "field": "documentDefinitionId.name",
                            "operator": "==",
                            "value": "loans"
                        },
                        {
                            "type": "field",
                            "field": "assigneeId",
                            "operator": "==",
                            "value": "${currentUsername}"
                        }
                    ]
                }
            ]
        }
    ]
}

For more information on container conditions, including CaseDefinition scoping, nesting containers, and a full list of available container relationships, see Container conditions.

Exporting permissions

Via UI

When exporting permissions from the permission configuration page, be sure to save the configurations first if any edits have been made. Exporting will add a few more fields that are not necessary when configuring permissions via the UI, but are necessary when doing auto-deployment.

exporting-permissions-example

Deleting permissions

Via UI

Deleting permissions will also delete the accompanying role. Deleting roles will not delete the role in Keycloak.

deleting-permissions-example