Skip to content

How-To: Give a CI/CD Pipeline Access to a Signing Key

Set up a CI/CD pipeline that signs with the FW key fw-prod, with one person approving each signing operation. You create two roles and two subjects; substitute your own key, role, and identity names.

Prerequisites

  • An INITIALIZED FW key, here fw-prod, with Required Approvers set to 1 (Create a New Key, or Edit an Existing Key; editing the key needs keyadmin)
  • A subject whose role includes the useradmin Nature, with an active administrative session
  • The pipeline's identity in your identity provider, and the value of its service-ID claim copied from an issued token. The claim per provider is listed in Create a subject
  • The approver's account in your identity provider, and its username claim value, typically an email address

Step 1: Create the pipeline role

Create a role named ci-orderer-fw-prod and add the fwsigner Nature with fw-prod ticked. The UI steps are in Create a New Role and Using Natures to Add Permissions.

Expected result: the role's permission table lists the fwsigner API names, each for fw-prod.

Step 2: Create the approver role

Create a role named fw-approver-fw-prod. Add the user Nature, then the approver Nature with fw-prod ticked.

Expected result: the permission table lists getconfigs and getuserinfo with no key, and approve, getapprovals and revokeapproval for fw-prod.

Step 3: Register the pipeline subject

Create a subject with:

  • Subject Type: Client
  • Subject ID: the pipeline's service-ID claim value, for example project_path:group/firmware:ref_type:branch:ref:main for a GitLab CI job
  • Associated Roles: ci-orderer-fw-prod

Step 4: Register the approver subject

Create a subject with:

  • Subject Type: User
  • Subject name: the approver's username claim value, for example jane.smith@company.com. Leave Subject ID empty unless you know the user-ID claim; the Keyserver records it at the user's first login
  • Associated Roles: fw-approver-fw-prod

Keep the two roles on separate subjects; see Why approvals exist.

Step 5: Check the setup

Check Must be If it is not
fw-prod on the Signing Keys page Status INITIALIZED, Required Approvers 1 Edit an Existing Key
Pipeline subject Type Client, Subject ID equal to the token's claim value, role ci-orderer-fw-prod Correct it as in Step 3
Approver subject Type User, role fw-approver-fw-prod Correct it as in Step 4

What happens at release time

  1. The pipeline requests an OAuth2 token from your identity provider.
  2. It calls POST /api/operations for fw-prod, for example with maxusagecount 1 and validms 600000. The Keyserver checks that the pipeline holds createoperation on fw-prod and creates the operation.
  3. The pipeline polls GET /api/operations/{id} until the operation is approved.
  4. The approver logs in, opens the Approvals page, reviews the description, and clicks Approve. The Keyserver checks that the approver holds approve on fw-prod.
  5. The pipeline calls POST /api/signorders with the hash. The Keyserver checks that the operation is approved and its usage count is not used up, and returns the signature.

The pipeline side is in GitLab CI, Azure DevOps and Integrate a Headless Build Server. The approver side is in Approval Workflow.

If something fails

Symptom Cause and fix
401 "The user/client is not valid" on every pipeline call The pipeline's Subject ID does not match its token's claim. Copy the claim value from an issued token (Step 3)
403 on POST /api/operations The pipeline role lacks fwsigner for fw-prod. Add the Nature with the key ticked (Step 1)
The approver cannot use the UI The approver role lacks the user Nature (Step 2)
The operation does not appear on the approver's Approvals page The approver role lacks approver for fw-prod (Step 2), or the operation is already approved, expired or cancelled
409 "Need more approvers" on POST /api/signorders The operation is not approved yet. Keep polling until it is
410 on POST /api/signorders The operation expired or was cancelled before signing, or one of its keys was revoked. Create a new operation, with a larger validms if the approval took too long

Other status codes: Error Codes.