Role¶
Roles in Digital Rebar Provision control which API operations a user is allowed to perform. Every API action (list, get, create, update, delete, and object-specific actions) is governed by a set of Claims that a Role grants. Users are assigned one or more roles.
Each role is checked independently, and a request is allowed if any one role covers it. Holding more roles can only ever grant more access, so a user with a read-only role and a separate update role can perform both kinds of operation.
The one subtlety: a single request that needs two permissions at once must find both in the
same role. Claims are not pooled across roles to satisfy one request. In practice this only
arises for a PATCH touching several fields, where each change is checked separately -- a role
granting update:/Name and a different role granting update:/Description will not between them
authorize one PATCH that changes both. This is long-standing behaviour and is unchanged.
How Roles Work¶
A Role is a named object that contains a list of Claims. Each Claim specifies three things: a
Scope (the object type, such as machines or bootenvs), an Action (such as get,
list, create, update, or delete), and a Specific (a particular object key, or * for
all objects of that type). All three fields accept comma-separated lists or * as a wildcard.
For example, a Claim with Scope machines, Action get,list, Specific * allows listing and
reading all machines but grants no write access. A user is granted access if any one of their
assigned roles satisfies the whole request on its own.
Listing Needs Get¶
On a DRP that advertises the profile-attach-rights feature, a list returns only the objects the
caller may get. list on a scope lets the caller
ask for the list. Each object in it also needs get, checked the same way a request for that one
object is. The count headers, limit, group-by and aggregate see the same set of objects.
A role that grants list without get on a scope therefore lists nothing there. Grant them
together, for example Action get,list. The stock readonly and operator roles in
drp-community-content from its release that requires profile-attach-rights grant get,list on ux_views, plugin_providers and
trigger_providers. Roles copied from older versions of them grant only list there, so the
portal loses the views its navigation uses. Add get to those scopes.
Adding a profile to an object also needs profiles get on that profile. See Cannot add profile X: requires profiles get X.
Built-in Roles¶
DRP ships with a built-in superuser role whose claims cover all scopes and all actions with a
wildcard specific. This role is assigned to the default rocketskates administrator user. Do not
delete the superuser role.
Creating Custom Roles¶
Create a role using drpcli or the portal:
# Create a read-only role for machine inspection
drpcli roles create '{
"Name": "machine-reader",
"Claims": [
{"Scope": "machines", "Action": "get,list", "Specific": "*"},
{"Scope": "bootenvs", "Action": "get,list", "Specific": "*"}
]
}'
To create an operator role that can update machine workflow and stage assignments but cannot delete machines:
drpcli roles create '{
"Name": "machine-operator",
"Claims": [
{"Scope": "machines", "Action": "get,list,update,action", "Specific": "*"},
{"Scope": "bootenvs,stages,workflows", "Action": "get,list", "Specific": "*"}
]
}'
Assigning Roles to Users¶
Roles are assigned by name on a User object. A user can hold multiple roles, and holding more roles can only ever grant more access. See User for how to assign roles when creating or updating users.
To let users read or manage their own params, give each one a role naming them. See User Self-Access Roles.
How Claims Are Matched¶
Claims are matched as patterns, not looked up in a list of known scopes. A request is allowed only if some claim in a single role positively covers it. Anything not positively covered is denied.
This has one consequence worth understanding: a scope or action that DRP does not recognise
matches nothing. It is not an error — it simply never satisfies any request. Writing a Claim
with Scope not-a-real-scope is harmless and grants no access.
Earlier releases worked the other way round, comparing each Claim against a fixed registry of known scopes. That had two failure modes, both now gone: an unrecognised scope was silently satisfied by any claim at all rather than denied, and the very scopes affected could not be granted, so there was no way to write a Claim that fixed the problem.
Role Validation¶
DRP validates a Role's structure when it is created or updated: the name must be valid, and a null Claim entry is rejected.
Claim content is not validated. An unrecognised scope or action is reported as an advisory diagnostic in the save response and does not prevent the Role from saving or being used. Nothing about a Claim's content can make a Role unusable.
This is deliberate. Claims are matched rather than looked up, so there is no authoritative list to validate against — and a Role naming a scope that a plugin registers later must remain usable across a restart, before that plugin has loaded.
Discovering Scopes and Actions¶
drpcli info get reports the scopes and actions the endpoint checks, under scopes:
Treat this as suggestions, not a permitted set. It is generated from the authorization checks the server actually performs, so it is an accurate description of what DRP looks at — but a Claim naming something absent from it still saves and is still enforced. The web UI's scope and action pickers offer these values while also accepting anything you type.
Roles in Content Packs¶
Roles can be included in content packs, making them easy to distribute as part of a content bundle. When a content pack is installed, its roles are loaded alongside tasks, stages, and workflows. This is useful for distributing a consistent RBAC posture across managed endpoints.