> For the complete documentation index, see [llms.txt](https://docs.valtimo.nl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.valtimo.nl/features/access-control/configuring-permissions.md).

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

{% hint style="info" %}
This page requires:

* Knowledge of [JSON](https://www.json.org/?_target=blank)
  {% endhint %}

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

{% tabs %}
{% tab title="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](/files/wTfDIM60CT0EW19l6Zmm)

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](/features/access-control/configurable-elements.md) the permission applies to and tick the [allowed actions](/features/access-control/configurable-elements.md) (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](/features/access-control/configuring-conditions.md): 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](/features/access-control/container-conditions.md)). Access is granted only when all conditions are met.
* **Context** — control whether the permission depends on the [context](/features/access-control/configuring-context-conditions.md) 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:

```json
[
  {
    "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](/features/access-control/configurable-elements.md). For information on how to register custom resource types, see the [registering a resource documentation](/features/access-control/for-developers/registering-a-resource.md).
* `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](/features/access-control/configurable-elements.md).
* `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](/features/access-control/configurable-elements.md). Permission is only granted when all conditions for that permission are met.
  {% endtab %}

{% tab title="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`:

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

```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](/features/access-control/container-conditions.md).
{% endtab %}
{% endtabs %}

## Exporting permissions

{% tabs %}
{% tab title="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](/files/jXqRR8h8AJbHK7Y9og4M)
{% endtab %}
{% endtabs %}

## Deleting permissions

{% tabs %}
{% tab title="Via UI" %}
Deleting permissions will also delete the accompanying role. Deleting roles will not delete the role in Keycloak.

![deleting-permissions-example](/files/IQC0dbvZEFrm5tWbXmQT)
{% endtab %}
{% endtabs %}