Skip to content

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 keyadmin Nature (key settings) and the useradmin Nature (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 reviewer Nature

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

  1. Click Roles in the navigation bar, then Create.
  2. Enter a Name, for example fw-approver-fw-prod, and a Description.
  3. Expand Signing Key Permissions ... and click Add natures to role ....
  4. Select the user Nature and click Add.
  5. Select the approver Nature, tick each key this role may approve, and click Add.
  6. 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

  1. 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.
  2. 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".
  3. 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 times
    Selected JWT Claims of the Pipeline Operation Creator Token claims chosen in the deployment configuration, such as a branch or pipeline ID
  4. Check the operation against the pipeline run it claims to come from, as described in What an approver authorizes.

  5. 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 revokeapproval on 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 without revokeapproval on 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 with DELETE /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 approve entry per approval, with the approver in Created By
  • a revokeapproval entry for each Revoke that cancelled the operation. A refused Revoke leaves no entry
  • a canceloperation entry if the pipeline cancelled the operation
  • the createoperation entry and any order or createcertificate entries 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.