Roles¶
The Keyserver uses role-based access control (RBAC). A role is a named set of permissions. Subjects do not hold permissions directly: they hold roles. A few built-in roles ship with the product (KEYADMIN, USERADMIN, REVIEWER) to cover common use cases and provide a starting point, while custom roles can be created for more advanced or security-sensitive setups.
A subject may hold any number of roles, so responsibilities can be kept in separate roles and combined per subject. Its effective permissions are the union of the permissions of all its roles.
Natures¶
It is recommended to build roles from Natures rather than adding individual permissions. A Nature is a predefined permission set for a common role type, such as fwsigner for a CI/CD pipeline or approver for a person who approves operations. Adding a Nature to a role writes its permissions into the role. The role stores only those permissions and does not record the Nature.
A Nature is either key-scoped or key-agnostic:
- Key-scoped (
fwsigner,devcertsigner,approver): each permission is bound to one signing key. When you add the Nature you tick one or more keys, and the role gets one permission per API name per ticked key. - Key-agnostic (
user,keyadmin,useradmin,authorizer,reviewer): the permissions are not tied to any key.
The API names each Nature adds are listed in the Nature reference.
Individual permissions¶
Use Natures where you can
In general, build roles from Natures. Permissions can also be added one at a time, for access that no Nature covers. They are stored the same way as the permissions a Nature adds. See Step 3: Create a New Role of the role management guide.
A permission pairs an API name, such as createoperation or approve, with an optional key ID. There are three permission types:
| Type | Grants access to | Example |
|---|---|---|
SIGNINGKEY | One action on one signing key | Create operations for fw-prod |
DATAKEY | One datastore entry; each entry needs its own permission | Fetch the value of firmware-enc-key |
UI | A key-agnostic administrative or read-only capability | View the audit log, manage roles, manage subjects |
Datastore access is granted in its own section of the role form; see Grant a client access to an entry.
The permission check¶
On every API call, the Keyserver combines the permissions of all roles the subject holds. The call must be allowed by at least one of those roles. If it is not, the request is rejected with 403 "Access forbidden".
For key-scoped API names, such as order, approve and getprivkeys, the permission must also name the key in the request: order on fw-dev does not grant order on fw-prod. A sign order needs order on every key in the operation, not only on the key being used.
Keep the subject that creates operations and the subject that approves them separate; see Why approvals exist. For diagnosing a 403, see Diagnosing 401 vs 404 vs 403.
Related pages¶
- Manage Roles: creating roles with Natures, and a worked example
- Subjects: the identities that hold roles