Upstream Authority Extension

The Upstream Authority Extension allows you to connect SPIRL to any external CA via an HTTPS webhook. Use this to integrate with corporate PKI systems, hardware security modules, or CA vendors not natively supported by SPIRL.

How it works

When the Trust Domain Server needs a new intermediate CA certificate (on startup or after a rotation), it calls the extension webhook with a certificate signing request (CSR). The webhook signs the CSR against the upstream CA and returns the signed certificate chain and the upstream CA roots. The Trust Domain Server then uses the issued intermediate CA to sign workload SVIDs.

How to Deploy

Step 1 — Implement the Webhook

The extension must implement the following endpoint:

POST /mint-x509-ca

Sign an intermediate CA certificate from the provided CSR.

Request:

{
  "csr": "-----BEGIN CERTIFICATE REQUEST-----\n...\n-----END CERTIFICATE REQUEST-----",
  "preferred_ttl": "2160h0m0s"
}

Response:

{
  "x509_ca_chain": [
    "-----BEGIN CERTIFICATE-----\n...signed intermediate CA...\n-----END CERTIFICATE-----",
    "-----BEGIN CERTIFICATE-----\n...issuing CA...\n-----END CERTIFICATE-----"
  ],
  "upstream_x509_roots": [
    "-----BEGIN CERTIFICATE-----\n...root CA...\n-----END CERTIFICATE-----"
  ]
}

Fields:

Field	Description
x509_ca_chain	Certificate chain in PEM format. The first certificate must be the newly signed CA corresponding to the public key in the CSR. Subsequent elements are intermediate CA certificates leading toward a root.
upstream_x509_roots	The root CA certificate(s) in PEM format. These are distributed to agents as the upstream roots in the SPIFFE trust bundle.

Return a non-2xx status code to reject the request. The Trust Domain Server will log the error and fail to start (or fail the rotation).

Step 2 — Update cluster configuration

section: UpstreamAuthority
schema: v1
spec:
  extensions:
    webhook:
      webhookURL: "https://my-ca-bridge.internal/upstream-ca"
      caCertPath: /etc/spirl/ca-bridge-ca.pem
      timeout: "30s"

Apply it using spirlctl:

spirlctl config set trust-domain-deployment --id <deployment-id> upstream-authority.yaml

Or using Terraform:

resource "spirl_cluster_config" "upstream_authority" {
  cluster_id = spirl_cluster.my_cluster.id
  sections = {
    UpstreamAuthority = <<-YAML
      section: UpstreamAuthority
      schema: v1
      spec:
        extensions:
          webhook:
            webhookURL: "https://my-ca-bridge.internal/upstream-ca"
            timeout: "30s"
    YAML
  }
}

Once a configuration document passes validation and is stored, the Defakto control plane syncs it to your Trust Domain Servers automatically. No server or agent restart is required.

Configuration Reference

Field	Required	Default	Description
webhookURL	Yes	—	Base HTTPS URL of the upstream authority extension.
authType	No	none	Authentication type for outbound requests: none or bearer.
tokenPath	No	/var/run/secrets/kubernetes.io/serviceaccount/token	Path to a file containing the bearer token. Required when authType is bearer.
timeout	No	30s	Maximum time to wait for a webhook response in Go duration format (e.g. 30s, 2m). CA signing may be slow for HSM-backed CAs.
caCertPath	No	—	Path to a PEM file containing custom CA certificates for TLS verification of the webhook endpoint. When empty, the system root certificates are used.

Step 3 — Verify

On startup, the Trust Domain Server logs the intermediate CA certificate it received from the extension. Check the trust bundle to confirm the upstream roots are present:

spirlctl trust-bundle get --cluster-id <cluster-id>

Security Considerations

• TLS required. The webhook must use HTTPS. Use caCertPath for private CAs.
• Webhook availability on startup. The Trust Domain Server cannot initialize if the webhook is unavailable during startup or CA rotation. Ensure high availability and a generous timeout for HSM-backed backends.
• CSR content. The Trust Domain Server generates the private key locally and submits only the CSR. The webhook never receives private key material.
• pathLen=0. The CSR requests a pathLen=0 constraint. Your CA must honor this. Issuing intermediate CAs with a larger path length would allow the Trust Domain Server to create unauthorized sub-CAs.
• Trust bundle propagation. The upstream_x509_roots returned by the webhook are distributed to all agents. Any change to these roots (e.g., CA rotation) triggers a trust bundle update across the fleet.