Trusted CAs
Steps that check a TLS server's certificate trust the public certificate authorities (CAs) in the worker's system trust store. A server whose certificate comes from a private CA, such as a lab's PKI or a company CA, then fails those checks ("unable to get local issuer certificate"), even though nothing is wrong with it.
An organization's admins fix that under Settings → Trusted CAs: they add the private CA's certificate, and from then on the organization's steps trust the system store plus that CA. Nothing in the flows has to change.
What Uses Them
probe.tls: the chain verdict (chain_ok) of live endpoints and of a pasted certificate. Its output'strust_storesays what chains were verified against:system+org,system, orca_bundle.probe.http: HTTPS checks with Verify TLS certificate on.http.request: requests with Verify TLS certificate on.- The
netbox.*steps, which send their requests throughhttp.request. container.run, when the step turns on Trust the organization's CAs (off by default; see Container Steps).
A step that sets its own CA bundle keeps the meaning it always had: it trusts only the certificates in that bundle, neither the system store nor the organization's trusted CAs. Use it to pin a server to one CA.
These steps come from the step plugins, which support trusted CAs from release 0.32.0; an older plugin release verifies against the system store alone, as before.
Which Organization's List Applies
The list of the organization the run belongs to. This mirrors how secrets are scoped: a run's steps read their own organization's secrets.
- A flow shared from the platform's shared organization and run by another organization trusts the running organization's CAs, not the shared organization's.
- The shared organization's list applies only to the shared organization's own runs, and it is not shown to other organizations.
- Two organizations' lists are never combined.
The worker never names the organization itself: it asks the API for the bundle of the step's run, and the API looks up the run's organization.
Adding a CA
- Open Settings → Trusted CAs and select Add CA.
- Give it a name and paste the CA certificate in PEM form (
-----BEGIN CERTIFICATE-----…). Check its fingerprint against the CA before you rely on it.
The API checks the PEM with the same rules as a webhook's custom CA bundle, and further:
- One certificate per entry. Add each CA (a root and an intermediate, say) as its own entry.
- Certificates only: a private key, a public key or any other PEM block is refused.
- At most 64,000 bytes.
- A certificate the organization trusts already (same SHA-256 fingerprint) is refused with the name of the existing entry, so a script can add CAs without creating duplicates.
The subject, the SHA-256 fingerprint and the validity dates are read from the certificate. The list marks a certificate that has expired or is not yet valid. Only the name of an entry can be changed; a new certificate is a new entry. A change applies from the next step that starts.
Certificates are public, so they are stored and shown as they are; they are not secrets. Adding, renaming and removing an entry is recorded in the audit log as a trusted_ca change.
Container Steps
Trust the organization's CAs on a container.run step places two read-only files in the container:
/hegemony/ca/ca-bundle.pem: the worker's system store followed by the organization's CAs.SSL_CERT_FILE,REQUESTS_CA_BUNDLEandCURL_CA_BUNDLEpoint at it, so OpenSSL, Pythonrequestsand curl trust public and private servers alike./hegemony/ca/org-cas.pem: the organization's CAs alone.NODE_EXTRA_CA_CERTSpoints at it; Node.js adds it to its built-in store.
The option is off by default because those first three variables replace the image's own trust store for the tools that read them: an image that brings its own CAs keeps working unchanged. A variable you set in the step's Environment Variables wins over the one the option sets. With no trusted CAs in the organization, the option changes nothing.
Permissions
| Action | Default role | What it allows |
|---|---|---|
trusted_ca:view | viewer | List the trusted CAs. |
trusted_ca:manage | admin | Add, rename and remove them. |
API
| Route | Action | Purpose |
|---|---|---|
GET /trusted-cas | trusted_ca:view (viewer) | Lists the organization's trusted CAs. |
GET /trusted-cas/{ca_id} | trusted_ca:view (viewer) | Shows one. |
POST /trusted-cas | trusted_ca:manage (admin) | Adds one: {"name": "Lab PKI", "pem": "-----BEGIN CERTIFICATE-----…"}. 409 when the certificate is trusted already. |
PATCH /trusted-cas/{ca_id} | trusted_ca:manage (admin) | Renames one: {"name": "Lab issuing root"}. |
DELETE /trusted-cas/{ca_id} | trusted_ca:manage (admin) | Removes one. |
Configuration Exchange
Trusted CAs are left out of configuration exchange exports, as trusted SSH host keys are: trust is granted by an admin who checked the certificate, and another deployment's admin adds the CAs it trusts rather than inherit trust it never granted.