Skip to content

Production Notes: Issue Device Certificates from CI/CD and Provisioning Pipelines

The complete device certificate flow is covered in:

→ Tutorial Part 3: Issue a Device Certificate Using the Trial Environment

It generates a device key pair and CSR, creates an operation for the CA key, submits the CSR to POST /api/certificates, and verifies the returned certificate chain. The API calls are the same in production. This page covers what changes when you move from the trial environment to an automated manufacturing or provisioning pipeline.

Provisioning Security Requirement

Provisioning systems must never use local password-based logins. Prefer short-lived OAuth2/OIDC tokens from your organization's identity provider or CI platform for CI pipelines, and the PKCE flow for provisioning stations that cannot hold a client secret.

A headless system that can store and rotate a client secret securely may use the Client Credentials grant instead. See Integrate a Headless Build Server.

Production differences from the tutorial

Authentication. Replace the internal-Authserver token from Step 8: Authenticate as the Provisioning Client of the device certificate tutorial with your production identity:

Device key generation. Generate the device key pair on the device or inside a secure element. The Keyserver only sees the CSR, so a device-generated key never leaves the device.

Where a device cannot generate its own key, injection is an exception that carries its own controls: generate the key on the provisioning line inside an HSM, transfer it over an authenticated channel, inject it into the secure element, and erase the line-side copy. Record and audit each exception. An injected key has existed outside the device, so the provisioning station is inside its trust boundary.

Batch operations. Create one operation per production run with maxusagecount set to the batch size, rather than one operation per device. A single approval then covers the batch, and the audit log ties every issued certificate to that approved operation through its operationid. In a batch run the common error is 409: the operation is not approved yet, or its maxusagecount is exhausted. See Error Codes Reference.

What a batch approval authorizes

The approval authorizes use of the CA key for a number of issuances within a time window. It is not bound to any CSR, subject name or device identity, and the approver does not see the devices. See What an approver authorizes.

A provisioning process compromised while an approved operation is open can submit any CSR and receive valid certificates, up to maxusagecount. Limit the exposure: size batches to the run without rounding up, set validms to the run length, and monitor issuance on the line.

Approvals. Production CA keys should require at least one approver. The pipeline creates the operation, then polls GET /api/operations/{id} until approved is true before it starts issuance. This is the same pattern as the signing pipelines in the CI guides.

Subject setup. The pipeline's client subject needs a role with the devcertsigner nature scoped to the CA key. It bundles createoperation, createcertificate, and the supporting read and cancel permissions. See Manage Roles in the Keyserver.