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