Skip to main content
Version: 🚧 Next

Roles

Business goal​

A role is a named set of permissions. Users get access to (parts of) the application through the roles assigned to them. Harmoney ships standard roles, and you can add custom roles next to them in Admin > Libraries > Roles.

A role is configured with:

  • identifier: the unique name of the role, e.g. DOSSIER_READER.
  • permissionRoot: a JSON object that defines what the role grants access to. See Permissions for how this object works, and the Permission reference for every namespace and scope you can use.

When a user holds several roles, the user gets the combined access of all of them.

Before you create custom roles, read Custom roles and migrations.

Legacy and standard roles​

For every legacy role of an FSP user, such as PARTNER_ADVISOR, there is a standard role with the _RBAC suffix, such as PARTNER_ADVISOR_RBAC. The standard roles exist to make the move from legacy roles to permissions smooth. They are not meant as a template for custom roles.

See Access control for how legacy and standard roles relate.

Translations​

The name of a role shown in the application comes from the translation BACK_END.VALUES.role.<identifier>.label. For example, PARTNER_ADVISOR is shown as "Advisor (legacy)" and PARTNER_ADVISOR_RBAC as "Advisor".

To give a custom role a readable name, add a white label translation with that code, e.g. BACK_END.VALUES.role.DOSSIER_READER.label, on every white label that uses the role. Without a translation, the identifier is shown.

Designing custom roles​

Keep custom roles small, each covering one task, and give a user several of them. Changing what a user can do is then a matter of adding or removing a role. Avoid one large custom role per user or per job: every change to it affects all users who hold it.

Example​

A role that only allows importing dossiers (DOSSIER_IMPORT):

{
  "fsp": {
    "dossier": {
      "set": {
        "permissions": {
          "dataImport": {}
        }
      }
    }
  }
}

A user who needs to read dossiers and import them gets DOSSIER_IMPORT together with a role that grants read access, instead of one role that combines both.

Custom roles and migrations​

Harmoney is moving the application from legacy roles to permissions one part at a time. Parts that have not moved yet still check the legacy roles. Parts that have moved check permissions only.

When a part moves, the upgrade adds the matching permissions to the standard roles. Users who hold both the legacy role and its standard role keep the same access. See Access control.

Custom roles are never changed by an upgrade. The application cannot know what a custom role is meant to allow, so it cannot decide which of the new permissions the role should get.

:::danger Users with a custom role can lose or gain access after an upgrade

A user who holds a legacy role together with a custom role, but without the standard role of that legacy role, loses access to every part that moves to permissions. The legacy role no longer counts there, and the custom role does not have the new permissions.

A user can also gain access. When a part moves to permissions, it can get a new sub-namespace below an existing namespace. A custom role that grants a scope higher in the tree, such as write on dossier, then grants it on the new sub-namespace as well, even if the user could not do this before.

:::

Reference​

The import envelope of a role. This is the shape of the JSON file that importing a role accepts and that exporting one produces.

warning

The permissionRoot structure below is generated from the code and is shown so that an exported role can be read back. It is not a stable contract: as stated above, the permission format may change without backwards compatibility, so custom roles remain strongly discouraged.

RoleExportDTO​

Settings Configuration

Examples