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
INITIALIZEDFW key, herefw-prod, with Required Approvers set to 1 (Create a New Key, or Edit an Existing Key; editing the key needskeyadmin) - A subject whose role includes the
useradminNature, 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:mainfor 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¶
- The pipeline requests an OAuth2 token from your identity provider.
- It calls
POST /api/operationsforfw-prod, for example withmaxusagecount1 andvalidms600000. The Keyserver checks that the pipeline holdscreateoperationonfw-prodand creates the operation. - The pipeline polls
GET /api/operations/{id}until the operation is approved. - The approver logs in, opens the Approvals page, reviews the description, and clicks Approve. The Keyserver checks that the approver holds
approveonfw-prod. - The pipeline calls
POST /api/signorderswith 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.
Related pages¶
- Access Control: how subjects, roles, and operations fit together