SPIFFE Workload API

Ghostunnel can obtain certificates and trusted roots from the SPIFFE Workload API. With the Workload API, Ghostunnel maintains up-to-date, frequently rotated client/server identities (X.509 certificates and private keys) and trusted X.509 roots. Peers are expected to present SPIFFE X509-SVIDs, which are verified using SPIFFE authentication.

To enable workload API support, set the SPIFFE_ENDPOINT_SOCKET environment variable or pass the --use-workload-api-addr flag. Either of these implicitly enables --use-workload-api, so the explicit flag is not required when the address is provided. You can also pass --use-workload-api on its own if the environment variable is already set.

On UNIX systems (Linux, macOS):

ghostunnel server \
    --use-workload-api-addr unix:///run/spire/sockets/agent.sock \
    --listen localhost:8443 \
    --target localhost:8080 \
    --allow-uri spiffe://domain.test/frontend

On Windows:

ghostunnel server `
    --use-workload-api-addr npipe:spire-agent\public\api `
    --listen localhost:8443 `
    --target localhost:8080 `
    --allow-uri spiffe://domain.test/frontend

Authorization #

The identity of the peer, i.e. the SPIFFE ID, is embedded as a URI SAN on the X509-SVID. Accordingly, the existing --verify-uri and --allow-uri flags can be used to authorize the peer.

Note that in client mode, SPIFFE authentication replaces the standard hostname verification that applies with other certificate sources: the server is verified as presenting a valid X509-SVID chaining to the trust bundle, not as matching the target hostname. Use --verify-uri to pin the expected SPIFFE ID.

The following examples show how to authorize peers in server and client mode:

As a server:

ghostunnel server \
    --use-workload-api \
    --listen localhost:8443 \
    --target localhost:8080 \
    --allow-uri spiffe://domain.test/frontend

As a client:

ghostunnel client \
    --use-workload-api \
    --listen localhost:8080 \
    --target localhost:8443 \
    --verify-uri spiffe://domain.test/backend

Startup Timeout #

At startup, Ghostunnel waits up to --use-workload-api-timeout (default 10m) for the first certificate to arrive from the Workload API before treating it as a fatal error. This covers deployments where the SPIRE agent is slow to attest at boot (e.g. fresh nodes, or ghostunnel racing spire-agent under systemd or Kubernetes). Setting the flag to 0 restores the pre-v1.11.1 behavior of waiting indefinitely.

Trust Bundle Updates #

When using the Workload API, Ghostunnel automatically watches for updates to both the X.509 identity (certificate and key) and the trusted root CA bundle. When the SPIFFE provider (e.g. SPIRE) rotates certificates or updates the trust bundle, Ghostunnel picks up the changes without requiring a manual reload or restart.

Demo #

See the end-to-end demo for an example using Ghostunnel with SPIFFE Workload API support backed by SPIRE. The SPIRE getting started guide covers setting up SPIRE from scratch on Linux/macOS.