Broker API overview

A broker is a process that handles network traffic for other workloads, such as a node-level proxy that terminates TLS on behalf of every pod on its node. Workloads behind a broker never present a credential themselves, so they never dial the SPIFFE Workload API for one. Something has to obtain SVIDs on their behalf.

The Broker API is how the Agent serves that case. A broker connects to the Broker Endpoint, a dedicated Unix domain socket on the Agent, and asks for credentials belonging to a workload it names. The endpoint is separate from the Workload API socket, mutually authenticated with SVIDs on both sides, node-local, and follows the SPIFFE Broker API specification.

The two sockets differ in what they authenticate and what they hand back:

	Workload API socket	Broker Endpoint
Caller authentication	Kernel peer credentials	Mutual TLS with the caller's own SVID
Credential returned	The caller's own identity	The identity of a third-party workload the caller names
Authorization	Attestation of the calling process	Allowlist in Managed Config, plus independent attestation of the named workload

When you need it

Enable the Broker API when a process needs credentials for workloads other than itself, and those workloads cannot use the Workload API directly. A sidecar-less service mesh such as Istio's Ambient Mode is the motivating case: One proxy per node originates and terminates mutual TLS for many pods, so it needs an SVID per pod rather than one for itself.

You do not need the Broker API for most deployments, where a workload can connect to the Workload API socket for its own credential. The Workload API authenticates each caller by kernel peer credentials and only ever returns that caller's own identity. This is a narrower trust relationship, so the Workload API is preferable in most cases.

What the endpoint serves

Four capabilities are available over the Broker Endpoint:

• X.509-SVID subscription: A stream of X.509 SVIDs for the named workload, refreshed as they rotate.
• X.509 bundle subscription: A stream of X.509 trust bundles, including federated bundles.
• JWT-SVID fetch: A single JWT-SVID for the named workload and a requested audience.
• JWT bundle subscription: A stream of JWT trust bundles in JWK form.

All four are served whenever the endpoint is enabled. Authorization is scoped by reference type, or how a broker is allowed to name a workload, and not by credential type. Every capability, including the two bundle subscriptions, requires naming a workload by reference and having that reference resolve successfully. Even though a bundle's contents do not depend on any particular workload, a broker cannot pull bundles for a workload it is not entitled to attest.

How it works

The broker authenticates as itself

The broker dials the Broker Endpoint using mTLS and presents its own SVID as a TLS client certificate. The Agent presents its own SVID as the serving certificate and validates the broker's certificate against the trust bundles it currently holds. A broker typically gets the SVID it presents from the Workload API, as an ordinary attested workload of the same Agent, and then turns around and presents that SVID on the Broker Endpoint.

Both sides track rotation without a restart. The Agent reads its current SVID on every handshake, so a rotated Agent SVID is served to the next connection without disturbing established ones. Client certificate validation reads live bundle state on every lookup rather than a snapshot taken at startup, so renewed intermediates and newly added federated bundles take effect immediately. TLS session resumption is disabled, so every new connection is authorized from scratch instead of inheriting a previous session's decision.

The endpoint does not begin listening until the Agent holds its own serving credential. Brokers never observe a half-configured endpoint, a non-SVID certificate, or a run of failed handshakes while the Agent starts up. Readiness is also rechecked per request rather than per connection: A broker that connects before trust bundles are loaded receives a retryable Unavailable status and then succeeds on the same connection once the Agent is ready.

The broker names a workload, and the Agent verifies it

A broker does not connect as the workload it wants a credential for. Instead it names that workload by reference: a Kubernetes pod object, or a process ID. Nothing vouches for a reference. The broker simply asserts it, which is why the Agent independently resolves every reference against a trusted node-local source before issuing anything.

Each request walks the same ordered path:

1. Admission. The broker's SPIFFE ID must appear in the cluster's BrokerPolicy section in Managed Config. A broker with no entry is rejected before its request reaches a handler.
2. Reference validation. The reference must be a recognized type and structurally valid. Validation happens before attestation, so a malformed reference never reaches a resolver.
3. Entitlement. The broker must be allowlisted for the reference type. This is enforced on every request, and it is checked before the Agent spends any work on resolution.
4. Resolution. The Agent resolves the reference against a node-local source: The kubelet's pod list for this node, or the Agent's own view of the node's processes. Resolution attests the named workload the same way the Workload API attests a caller, and produces the workload's attributes.
5. Issuance. The attested attributes go to the Trust Domain Server, which renders the SPIFFE ID from the cluster's identity template and issues the credential. A brokered workload therefore receives exactly the identity it would receive through the Workload API.

Shown for the X.509-SVID subscription.

Subscriptions are re-verified for the life of the stream

A brokered subscription is held by the broker, not by the workload the credential belongs to, so nothing about the workload's own lifecycle ends the stream. The Agent re-verifies each open subscription every 5 minutes instead. Every tick rechecks the broker's entitlement and then re-resolves the reference, in that order, so a broker that has lost its entitlement never spends a resolution.

Re-verification is what bounds revocation:

• Removing a broker from BrokerPolicy terminates its streams with PermissionDenied at the next tick.
• The referenced workload disappearing terminates the stream with NotFound.
• A reference resolving to a different workload than it originally did, such as a recycled pod name, terminates the stream with FailedPrecondition.

The revocation-to-termination bound is therefore up to 5 minutes after a policy change reaches the Agent, not instantaneous.

Everything is fail-closed

• The Broker Endpoint is off unless a socket path is configured. See Enabling the Broker API.
• An absent BrokerPolicy section and an empty broker list are equivalent: Both deny every broker.
• A broker that is allowlisted but not entitled for the reference type it used is denied that request.
• If the Agent has no trust bundles yet or cannot reach its policy, it fails the request with an error rather than serving it unchecked.

Security model

Allowlisting a broker is a delegation of trust. The sections below state exactly how far that delegation reaches.

What a compromised broker can obtain

A broker that is allowlisted can obtain SVIDs for any workload that meets all of these conditions:

• The broker can name the workload with a reference type its policy entry entitles it to use.
• The workload resolves on the node where the broker itself runs.
• The broker's entitlement is still in place, or was revoked less than one re-verification interval ago.

Those conditions are the whole of the delegation. A broker entitled to a reference type can obtain credentials for any workload on its node that it can name with that type. Scope entitlements narrowly, list the specific reference types a broker needs rather than the wildcard, and treat the broker's own identity as sensitive: Anything holding the broker's SVID is the broker as far as the Agent is concerned.

What a compromised broker cannot obtain

• Anything at all, without being allowlisted. A broker whose SPIFFE ID has no BrokerPolicy entry is rejected at every request. An absent or empty policy denies every broker.
• Credentials named with a reference type it is not entitled to. Reference-type entitlement is enforced per request and on every re-verification, not only when the connection opens.
• Credentials for a workload that does not resolve on its node. Resolution consults node-local sources only, so a reference to a workload on another node does not resolve.
• Anything as a broker from another trust domain. A BrokerPolicy entry must name a SPIFFE ID in the cluster's own trust domain. Cross-trust-domain brokers are not supported.
• Anything over the network. The Broker Endpoint listens only on a Unix domain socket, and both reference types are rejected outright over any non-local transport.
• A continuing stream after revocation. Open streams end at the next re-verification, bounded by 5 minutes.
• Credentials for a recycled name. A reference is pinned to the workload it first resolved to. A pod deleted and replaced by a same-named pod mid-subscription is detected, and the stream terminates rather than serving credentials for the replacement.

Blast radius

Blast radius is node-scoped, and that follows directly from resolution being node-local. The Agent resolves references against the kubelet's pod list for its own node and its own view of the node's processes. Neither source can name a workload elsewhere in the cluster, so a compromised broker instance reaches only the workloads on the node it runs on. The nodes a broker runs on are the extent of its reach.