Roles and permissions

Roles live under Roles in barakoBrew. A role is a name, a description, a set of per-content-type permissions and a set of system capabilities. This page covers what the role form edits and the two rules that catch people out. It describes barakoBrew 1.10.0 against barakoCMS 5.x.

Content permissions

The matrix has one row per content type and four boxes: create, read, update and delete. Grants add up across a user's roles. If any role allows an action, the user has it.

Against an API that speaks contract 6 or later (barakoCMS 4.6), each row also opens to conditions and field limits. A condition narrows an action to entries that match, for example entries the user created. A read rule can list the fields it shows, and a create or update rule can list the fields it lets the user set. Allow the action first, because conditions and field limits belong to an action.

Capabilities

A capability is a named permission for something that is not a content type: managing users, reading the audit log, retrying workflow actions. The role form shows the known ones as labelled checkboxes, such as Manage roles (manage_roles), Manage settings (manage_settings) and Retry workflow actions (retry_workflow_actions). A module's capability that is not listed, such as upload_files, is added by name under Other capabilities.

Since barakoCMS 4.0 the API checks capabilities, not role names. A role called "Editor" and a role called "Admin" differ only in what they hold. The name decides nothing by itself, so read the capabilities, not the name, when you want to know what a user can do.

A few capabilities reach past one tenant. barakoBrew marks them Platform: *, manage_roles, manage_platform_roles, manage_tenants, manage_users, manage_email_settings and view_hidden. Only a SuperAdmin can give a user a role that holds one. From barakoCMS 5.0, only a holder of manage_platform_roles can add one to a role, and the checkbox is disabled for anyone else.

manage_roles hands over the deployment

manage_roles is the capability to create and edit roles. A role that holds it can edit itself, so it can grant itself any other capability. It is not in the default Admin capabilities. Only SuperAdmin holds everything by default.

Grant it as you would give someone the keys. A grant of manage_roles is a grant of every capability. barakoCMS 4.1.0 closed a privilege escalation that turned on exactly this (GHSA-2522-rpv2-6p99). barakoBrew is where somebody clicks that checkbox, so decide who needs it before you do.

Reserved role names

The API refuses to create a role, or rename one, to SuperAdmin, Admin or User, in any letter case. The response is a validation error reading "'' is reserved for a built-in role. Choose another name." barakoBrew does not check the name itself. It shows the API's message when the save is refused.

Contract 3 (barakoCMS 4.1.0) added the rule. It also reserved HR, which barakoCMS 4.6.0 and later no longer reserves.

Platform roles and tenant roles

From contract 8 (barakoCMS 5.0) a role belongs to one tenant or to the whole deployment. The Roles list labels the owner: Platform, or the tenant's slug. SuperAdmin, Admin and User are platform roles. Changing or deleting a platform role needs manage_platform_roles, so barakoBrew does not offer those actions without it.

A built-in role is marked as such and cannot be deleted. Neither can a role while users still hold it. Unassign it first.

Giving a user a global role goes through the Users screen and applies in every tenant. The API takes only a platform role there, and it needs the caller's own manage_user_membership to come from a global role. A tenant admin gives roles inside the tenant through Members on the Tenants screen. A refusal from the API is shown with the API's own wording.