How-To: Set Up and Run Approval Workflows¶
Configure a signing key so that its operations need human approval, give approvers the right role, and approve or revoke pending operations in the Keyserver UI. Why approvals exist and what an approval authorizes are in Approval Workflow.
Prerequisites¶
- Access to the Keyserver UI at
https://keyclient.<UNIQUE-ID>.cryptera-security.io - For the setup steps: a subject whose roles include the
keyadminNature (key settings) and theuseradminNature (roles and subjects), and an administrative session - For each approver: a user subject in the Keyserver. See Manage Subjects in the Keyserver.
- For Step 6: a role with audit-log read access, such as one built from the
reviewerNature
Step 1: Set Required Approvers on the key¶
Start an administrative session, then click Keys in the navigation bar.
- New key: set Required Approvers in the create form, as in Step 3: Create a New Key of the key management guide.
- Existing key: click the pencil icon, change Required Approvers, and click Save, as in Step 5: Edit an Existing Key of the key management guide.
- Imported key: the import form has no Required Approvers field, so the key starts at
0. Edit it after the import. See Step 5b: Import an Existing Key of the key management guide.
Choose the count from Required approvers per key. The count must not exceed the number of subjects that will hold the approver Nature on the key, or no operation on it can ever be approved.
A new count is applied when an operation is created and each time it is approved. Operations that are already approved stay approved. Change the count when no operation on the key is pending. Lowering it while an operation is pending strands that operation: it leaves the Approvals list and reports approved: true, but every sign order on it fails with 400 "Validation error". Have the pipeline create a new operation, or restore the old count, after which the stranded operation can be approved again.
Step 2: Create an approver role¶
- Click Roles in the navigation bar, then Create.
- Enter a Name, for example
fw-approver-fw-prod, and a Description. - Expand Signing Key Permissions ... and click Add natures to role ....
- Select the user Nature and click Add.
- Select the approver Nature, tick each key this role may approve, and click Add.
- Click Save.
The approver Nature adds approve, getapprovals and revokeapproval for the ticked keys. See Nature reference. The UI shows Approvals in the navigation bar only to subjects that hold both getapprovals and approve.
Step 3: Assign roles to separate subjects¶
Assign the approver role to each approver's user subject, and the signing role (fwsigner or devcertsigner) to the pipeline's client subject. See Step 5: Associate Subjects with a Role of the role management guide.
Keep operation creators and approvers apart
The Keyserver does not check whether the approver created the operation. Never give one subject both a signing Nature and approver on the same key; see Why approvals exist.
Before handing over to the pipeline, open the Dashboard and check the KeyServer Status card:
| Check | Must be | If it is not |
|---|---|---|
| Operational row | This key is not listed | Open the info button. A key that requires more approvers than subjects allowed to approve it blocks every operation on it; add approvers or lower the count. Other warnings list keys with no subject allowed to create operations, order or create certificates; for this key, check the pipeline role from this step |
| Security row | No subject you set up in this how-to is named | Open the info button. It names each subject that holds an ordering permission and approve on keys of the same type (FW or CA), even on different keys. If a named subject can order and approve the same key, remove one of the roles |
Step 4: Notify approvers¶
The Keyserver sends no notifications. Have the pipeline alert approvers through your own channel when it creates an operation, for example a chat message carrying the operation ID, the build, and the expiry time. The operation expires validms after creation whether or not it was approved, so allow for approver response time when the pipeline sets validms. See Validity window.
Step 5: Approve or revoke an operation¶
- Log in to the Keyserver UI as the approver and click Approvals in the navigation bar. If your role also grants statistics access, the Pending approvals count on the Dashboard's Approvals card shows the operations still awaiting approval on keys you can approve.
- The Approvals pending list shows each operation you can still approve, newest first, with Created Date, Created By, Operation ID and Description. When there is nothing to approve, the page reads "There are no Pipeline Operations awaiting approval".
-
Click View on the operation. The panel shows:
Field Contents Operation ID, Created by, Created Date The operation and the subject that created it Valid time, Expires The validity window and the time it ends Approvers Subjects that have approved so far Description of the operation to approve Text written by the pipeline Signingkey usage description Each key and how many times it may be used, for example fw-prod: 1 timesSelected JWT Claims of the Pipeline Operation Creator Token claims chosen in the deployment configuration, such as a branch or pipeline ID -
Check the operation against the pipeline run it claims to come from, as described in What an approver authorizes.
- Click one of:
- Approve to count your approval toward every key in the operation that your role lets you approve. Once every key has its required approvals, the operation is approved and leaves the list. If it still needs other approvers, it stays listed and Approve is disabled for you.
- Revoke, then Revoke again in the "Are you sure?" dialog, to cancel the whole operation for every approver and key. This cannot be undone; the pipeline must create a new operation. Revoke needs
revokeapprovalon every key in the operation. The panel closes and the list reloads without the operation. If it is still listed after you reload the page, it was not cancelled. The usual cause is a role withoutrevokeapprovalon one of its keys: the Keyserver refuses the request, and the page may not say so. Ask the other approvers not to approve it, and have the pipeline owner cancel it withDELETE /api/operations/{id}or let it expire. - Close to leave the operation pending.
An operation that expires before it is approved leaves the list on the next page load.
Step 6: Verify what was approved¶
Click Audit in the navigation bar, enter the operation's ID in Operation ID, and click Search, as in Step 3: Filter Audit Logs of the audit log guide. The results show:
- one
approveentry per approval, with the approver in Created By - a
revokeapprovalentry for each Revoke that cancelled the operation. A refused Revoke leaves no entry - a
canceloperationentry if the pipeline cancelled the operation - the
createoperationentry and anyorderorcreatecertificateentries made under the approval
To review one approver's activity across operations, filter Select API Name on approve and Select Created By on the approver's subject.
If something fails¶
| Symptom | Cause |
|---|---|
| Approvals missing from the navigation bar | The subject's roles lack approve or getapprovals. Add the approver Nature (Step 2) |
| The operation is not in the Approvals pending list | Your role has no approve on any key in it that still needs approvals, or it is already approved, expired or cancelled |
| 409 "User has nothing in this operation (left) to approve" | Every key you can approve in the operation already has its required approvals, or you hold approve on none of its keys |
| 409 "A user can only approve once" or "Operation is already approved" | You approved it earlier, or another approver completed it while the panel was open. Reload the page |
| Revoke shows an error, or the operation is still listed after you reload | It was not cancelled. Your role lacks revokeapproval on at least one key in the operation, or the operation was already cancelled. Ask the other approvers not to approve it, and have the pipeline cancel it (DELETE /api/operations/{id}) or let it expire |
| 410 "Operation is cancelled" | Another approver revoked it, or the pipeline cancelled it |
| The pipeline gets 409 "Need more approvers" | At least one key in the operation is still short of approvals, even if the pipeline only uses another key (Approval applies to the whole operation) |
| The pipeline gets 410 after approval was given | The operation expired, was cancelled, or a key in it was revoked. The pipeline must create a new operation |
Full status-code causes are in Error Codes.