Access Control¶
The Keyserver controls every signing and administrative action with three building blocks:
- Subjects: who is acting.
- Roles: what they are allowed to do.
- Operations: the time-limited ticket that gates key usage.
Configuring subjects, roles, and keys requires an active administrative session. For a worked setup, see Give a CI/CD Pipeline Access to a Signing Key.
Authorization model¶
flowchart TB
U(["User<br/>a person: approver,<br/>administrator, reviewer,<br/>station operator"])
C(["Client<br/>a machine: CI/CD pipeline,<br/>provisioning tool, service"])
S["Subject"]
R["Role"]
N["Nature<br/>template, applied when added"]
P["Permission<br/>API name + optional key ID"]
K["Signing key<br/>ROOT, CA or FW"]
D[("Datastore entry")]
O["Operation"]
U -->|is a| S
C -->|is a| S
S -->|"holds 0..* roles"| R
R -->|"stores 0..* permissions"| P
N -.->|"expands into, when added"| P
P -->|"SIGNINGKEY type: one key"| K
P -->|"DATAKEY type: one entry"| D
S -->|"creates or approves"| O
O -->|"names 1..* keys"| KDiagram: User a person: approver, administrator, reviewer, station operator; Client a machine: CI/CD pipeline, provisioning tool, service; Subject; Role; Nature template, applied when added; Permission API name + optional key ID; Signing key ROOT, CA or FW; Datastore entry; Operation; is a; holds 0..* roles; stores 0..* permissions; expands into, when added; SIGNINGKEY type: one key; DATAKEY type: one entry; creates or approves; names 1..* keys
A role stores permissions and nothing else. A Nature is a template: adding it to a role writes its permissions into the role, and the role does not record which Nature added them. Each permission pairs an API name with a key ID. The key ID names a signing key (SIGNINGKEY permissions) or one datastore entry (DATAKEY permissions); UI permissions have none.
Subjects¶
A subject is the Keyserver's record of an identity issued by your authorization server. Every API call and UI action is performed by a subject. See Subjects.
Users¶
A user is a person who logs in to the Keyserver UI, including an operator at a provisioning station. See Users.
Clients¶
A client is a non-interactive system, such as a CI/CD pipeline or a headless provisioning tool. See Clients.
Roles¶
A role is a named set of permissions, usually built from Natures. A subject's permissions are the union of its roles' permissions. See Roles.
Operations¶
An operation is a time-limited ticket naming which keys may be used and how many times. Signing and certificate issuance require an approved operation. See Operations and Approval Workflow.
How access control is evaluated¶
Every API call passes these checks. A call that fails one is rejected.
1. Authentication¶
The request must carry a valid OAuth2 access token: correctly signed, not expired, and from a configured issuer with a matching audience. Otherwise it is rejected with 401. See Token Validation.
1a. Subject mapping¶
The token's identity claim must match a registered subject, or the request is rejected with 401 "The user/client is not valid". See Token-to-subject mapping.
2. Permission check¶
At least one of the subject's roles must grant the API call, for the key in the request when the API name is key-scoped. Otherwise the request is rejected with 403 "Access forbidden". See The permission check.
3. Operation check¶
POST /api/signorders and POST /api/certificates also require an operation that exists, has not expired or been cancelled, includes the target key, and is approved. Each failure returns its own status; see Using an operation.