What is SPIFFE workload identity and how does it enable service to service mTLS?

A SPIFFE ID is a URI that names a workload: spiffe://trust-domain/path. The trust domain, such as prod.example.internal, marks an administrative boundary with its own signing authority. The path is a naming scheme you choose, for example /ns/payments/sa/ledger. The ID names what a workload is. It says nothing about where the workload runs.

An X.509-SVID (SPIFFE Verifiable Identity Document) is an ordinary X.509 certificate that carries exactly one SPIFFE ID in its URI Subject Alternative Name. SVIDs are short-lived by design, typically hours rather than months. Because they expire quickly, a leaked key stays useful only briefly, and the system relies less on revocation, which works poorly in practice.

The trust bundle is the set of CA certificates for a trust domain. A peer's SVID is valid if it chains to a bundle you hold. Holding a bundle means you trust that domain to make identity claims. Federation means holding more than one domain's bundle.

Hostname and IP-based trust breaks down in dynamic infrastructure. Pod IPs get reused, several services can share a node, and a DNS name only tells you where traffic was routed, not which code is answering. With identity-based service to service mTLS, both sides prove a cryptographic identity, and authorization rules are written against those IDs.

Without a mesh, no sidecar handles any of this for you. Each application fetches its own SVID and bundle and accepts updates as they rotate. In exchange, it owns:

  • its TLS configuration
  • peer-ID authorization checks
  • correct handling of certificate rotation

How does SPIRE issue identities through the Workload API?

SPIRE splits identity issuance between two components.

The SPIRE Server is the signing authority. It holds the trust domain's signing keys and a set of registration entries. Each entry maps a SPIFFE ID to the conditions a workload must meet to receive it. Nothing gets an identity unless an entry says it should.

The SPIRE Agent runs on every node and attests in two stages:

  • Node attestation. The Agent proves which machine it is running on, for example with a Kubernetes projected service account token or a cloud provider's instance identity document. The Server then knows the Agent and which entries it may serve.
  • Workload attestation. When a process connects, the Agent reads the caller's PID from the kernel through the socket's peer credentials. It then gathers selectors about that process, such as Kubernetes namespace and service account (looked up from the kubelet) or Unix UID. If the selectors match a registration entry, the workload gets that entry's SPIFFE ID.

This design is why the Workload API needs no pre-shared secret. It is served over a local Unix domain socket, and the kernel vouches for the caller, so there is no bootstrap token to distribute or leak.

The API is a stream. The workload opens a connection and receives its SVID and trust bundle. It then receives new ones as they rotate or as federated bundles change. Nothing is written to disk to be polled, so there is no window where a file is half-written or stale.

The cost is operational. The Server and Agents are now critical-path infrastructure. Agents cache SVIDs, so they can ride out a brief Server outage. If the Server stays down longer than the SVID lifetime, issuance stops and new connections start failing. A failed Agent takes every workload on its node with it.

+------------------------------------------------------------+
| SPIRE Server (signing authority for the trust domain)      |
|   signing keys  |  registration entries                    |
|                 |   spiffe://example.org/billing           |
|                 |     <- k8s:ns:billing, k8s:sa:billing    |
|                 |   spiffe://example.org/batch             |
|                 |     <- unix:uid:1001                     |
+------------------------------------------------------------+
        ^                                   |
        | 1. node attestation               | 2. entries + SVIDs
        |    (k8s PSAT or cloud instance    |    for this node
        |     identity document)            v
+------------------------------------------------------------+
| Node                                                       |
|  +------------------------------------------------------+  |
|  | SPIRE Agent (caches SVIDs)                           |  |
|  | 3. workload attestation:                             |  |
|  |    peer creds -> PID -> selectors (kubelet, UID)     |  |
|  +------------------------------------------------------+  |
|        ^ Workload API          | 4. stream: SVID + bundle  |
|        | connect, no secret    |    then rotations         |
|        | over Unix socket      v                           |
|  +------------------------------------------------------+  |
|  | Workload process  (ns=billing, sa=billing)           |  |
|  +------------------------------------------------------+  |
+------------------------------------------------------------+

The SPIRE Agent attests its node to the Server, then attests each local process through kernel peer credentials on the Workload API socket and streams it the SVID and bundle for the matching registration entry.

How do you implement mTLS in application code with go-spiffe?

In Go, the go-spiffe library does most of the work. The application opens a workloadapi.X509Source once at startup. The source holds a streaming connection to the Agent and swaps in new SVIDs and trust bundles as they arrive. Pass that same source to tlsconfig.MTLSServerConfig on the server and tlsconfig.MTLSClientConfig on the client, and use it as both the certificate provider and the bundle source. The TLS config reads from the source on every handshake, so a rotated certificate is used on the next connection without a restart or file reload. Close the source on shutdown.

Both helpers take an authorizer, and that authorizer replaces hostname verification. SPIFFE certificates identify workloads by URI SAN, not DNS name. A client should therefore check that it reached the expected service with tlsconfig.AuthorizeID for a single ID or AuthorizeOneOf for a short allowlist. A server that accepts any caller in its trust domain can use AuthorizeMemberOf. A server that applies path rules can write a custom authorizer.

A completed handshake proves who the caller is, not what it may do. Keep per-endpoint permission checks in the application. Extract the peer ID with x509svid.IDFromCert and evaluate it there.

Identities come from registration entries, for example: spire-server entry create -parentID <agent-id> -spiffeID spiffe://example.org/billing -selector k8s:ns:payments -selector k8s:sa:billing. Review these changes the way you review firewall rules, because whoever controls the selectors controls who receives an identity. A namespace-only selector hands the identity to every pod in that namespace. A per-cluster identity makes every service indistinguishable to its peers. Use one identity per service, with the narrowest selectors that still match.

// Go (go-spiffe v2): one live X509Source shared by client and server TLS configs
package main

import (
	"context"
	"log"
	"net/http"

	"github.com/spiffe/go-spiffe/v2/spiffeid"
	"github.com/spiffe/go-spiffe/v2/spiffetls/tlsconfig"
	"github.com/spiffe/go-spiffe/v2/svid/x509svid"
	"github.com/spiffe/go-spiffe/v2/workloadapi"
)

func main() {
	ctx := context.Background()
	// Opened once. It streams rotated SVIDs and bundles from the Agent (socket from SPIFFE_ENDPOINT_SOCKET).
	source, err := workloadapi.NewX509Source(ctx)
	if err != nil {
		log.Fatal(err)
	}
	defer source.Close()

	// Client: confirm we reached billing by its SPIFFE ID, not by hostname.
	billingID := spiffeid.RequireFromString("spiffe://example.org/billing")
	_ = &http.Client{Transport: &http.Transport{
		TLSClientConfig: tlsconfig.MTLSClientConfig(source, source, tlsconfig.AuthorizeID(billingID)),
	}}

	// Server: the TLS layer admits any workload in the trust domain. That check is identity only.
	td := spiffeid.RequireTrustDomainFromString("example.org")
	canRefund := map[string]bool{"spiffe://example.org/checkout": true}
	mux := http.NewServeMux()
	mux.HandleFunc("/refunds", func(w http.ResponseWriter, r *http.Request) {
		// Permission is a separate, per-endpoint decision made in the application.
		id, err := x509svid.IDFromCert(r.TLS.PeerCertificates[0])
		if err != nil || !canRefund[id.String()] {
			http.Error(w, "forbidden", http.StatusForbidden)
			return
		}
		w.Write([]byte("ok"))
	})
	srv := &http.Server{Addr: ":8443", Handler: mux,
		TLSConfig: tlsconfig.MTLSServerConfig(source, source, tlsconfig.AuthorizeMemberOf(td))}
	log.Fatal(srv.ListenAndServeTLS("", "")) // Certificates come from the source, so no file paths are needed.
}

A Go service builds its mTLS client and server configs from one live X509Source, so rotated SVIDs are used without a restart; peers are authorized by SPIFFE ID at the TLS layer, and per-endpoint permission is checked separately in the handler.

How does certificate rotation work, and where does it break?

X.509-SVIDs are deliberately short-lived, typically hours rather than months, so a leaked key stops being useful quickly. The SPIRE Agent renews each SVID well before it expires, commonly around the halfway point of its lifetime, and pushes the new certificate and bundle over the Workload API stream. go-spiffe's X509Source swaps them in memory, and new handshakes pick them up without a restart. File-based delivery adds a second hop that can fail: something writes the files, and something else has to notice and reload them.

Leaf rotation happens automatically. CA and trust bundle rotation does not stay inside one service. When the signing CA changes, every relying party must trust the new root before any SVID is signed by it. Federated domains owned by other teams must also pull the updated bundle. Plan overlap windows and confirm propagation before retiring the old CA.

Rotation bugs tend to appear late, often first at the TTL boundary:

  • Cached TLS configs. Code that copies a certificate into a static tls.Config at startup works until that certificate expires.
  • Connection pools. Established connections keep their original handshake. They can mask a broken renewal path for hours and then fail all at once.
  • File-watch reloaders. Atomic renames, symlink swaps and inotify edge cases can cause a reloader to miss updates without logging anything.

TTL versus resilience

Illustrative estimate, assuming a 1-hour TTL and renewal at 50%: a freshly renewed workload holds a certificate valid for 60 minutes. If the agent loses contact with the SPIRE Server just before a scheduled renewal, the workload has about 30 minutes of remaining validity. A 24-hour TTL would give about 12 hours. Shorter TTLs reduce exposure from a stolen key, but they also shorten how long a server or agent outage can last before handshakes start to fail. Choose the TTL based on how quickly you can restore those components.

What are the alternatives when a workload can't use a SPIFFE library?

When a workload is written in a language without a maintained SPIFFE library, or is a third-party binary you can't modify, move the Workload API client out of the process. The common pattern is a helper process, such as spiffe-helper, that fetches SVIDs and trust bundles from the local SPIRE agent, writes them to disk as PEM files, and signals a stock TLS proxy to reload. The application then speaks plaintext to the proxy over loopback, and the proxy handles mTLS on the network.

This works, but it has costs that the in-process library avoids:

  • File reload races. The proxy can read a new certificate before the matching key has been written, or keep serving an expired SVID if the reload signal is lost. To avoid partial reads, write files atomically with a rename, and alert on certificate age rather than on reload events.
  • Configuration drift. SPIFFE ID authorization moves into each proxy's configuration. Those configurations are maintained separately from the application, so they tend to diverge.
  • Weaker identity at the application layer. The application sees a loopback connection. It only learns the peer's identity if the proxy forwards it in a header, which the application must trust.
Approach Rotation handling Where authorization lives Per-language effort Polyglot consistency Operational burden Retries, traffic shifting, per-request telemetry
In-app library In memory, no restarts Application code High Low Low None
Helper + proxy File write plus reload signal Proxy config Low Medium Medium Depends on proxy
Full service mesh Handled by the mesh Mesh policy None High High Built in
Central gateway Only at the gateway Gateway None High Medium At the gateway only; internal hops remain unauthenticated

How do you debug and monitor SPIFFE-based mTLS?

Without a proxy layer, nothing records who called whom unless your services do it. Log the peer SPIFFE ID, local ID, and handshake outcome on every accepted and initiated connection. Rejections matter most, because a denied peer usually means a misconfigured caller and not an attack. Emit these as structured fields so you can build a caller-to-callee graph, which a mesh would otherwise give you for free.

Alert on two things. First, alert on SVID remaining lifetime falling below about half its TTL, since that means rotation has stalled. Second, alert on SPIRE agent health through its health check endpoint. An unhealthy agent doesn't break connections right away. It breaks them when current SVIDs expire, so you have a window to act.

Symptom Likely cause First check
"Unknown authority" or chain verification error Wrong or stale trust bundle, often across trust domains Compare the bundle the workload holds with the issuing server's bundle
Handshake completes, then the authorizer rejects Peer's URI SAN doesn't match the expected ID Inspect the peer certificate's URI SAN with openssl x509 -text
"Not yet valid" or "expired" on fresh certs Clock skew between nodes Check NTP sync on both hosts
Startup hangs or fails fetching an SVID Workload API socket unreachable Confirm the socket is mounted at the configured path and that spire-agent api fetch x509 succeeds from inside the workload

Budget time for the learning curve. Engineers used to hostname checks often look for identity in the CN or DNS SANs. They also tend to treat the Workload API as a file on disk when it is really a streaming local API.

When should you use SPIFFE without a mesh, and when should you avoid it?

Good fit

SPIFFE without a mesh works best when most services are written in one or two languages that have mature SPIFFE libraries, such as Go. Every service then shares the same mTLS setup and the same authorization check against peer SPIFFE IDs, and you avoid running a sidecar next to every pod. The prerequisite is a platform team that can run SPIRE as critical infrastructure. If the SPIRE server or agents fail, workloads can't renew their SVIDs, and when those SVIDs expire, calls between services start failing.

When to avoid it

In a polyglot fleet, each language needs its own integration. The usual result is uneven TLS configuration and authorization logic duplicated across codebases, with differences that nobody audits. If you depend on retries, traffic shifting, or outlier detection, you would be rebuilding mesh features by hand. If compliance requires policy that is enforced and changed centrally, scattered in-process checks are a weak substitute.

Federation and the tipping point

To span clusters or environments, give each one its own trust domain. SPIRE servers then exchange trust bundles through bundle endpoints, and workloads receive the federated bundles through the Workload API. This works well for a few trust domains. Once you are managing many federation relationships and authorization rules that cross domains, a mesh or gateway that centralizes policy is usually cheaper to run.

Weighing cost

The costs are per-language library work, duplicated logic, and building replacements for any mesh features you need. Against that, you remove sidecar operations, you no longer manage certificates tied to IPs or hostnames, and you stop handling manual certificate distribution and rotation tickets.

How OneEnv can help

Disclosure: OneEnv is the product behind this blog.

OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.

Applied to service to service mtls, this is where it helps:

Saves time

  • Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
  • One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
  • Changing a shared variable is one edit and one review instead of editing every service's .env by hand.

Saves cost

  • Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
  • Less duplicated configuration to maintain: one shared definition inherited by many services.
  • A wrong or stale value is caught at review time by the services it affects, not by a failed deploy.
  • OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.

These are qualitative benefits, not measured results — how much you save depends on how many services share the value.

Want to try it? Start at oneenv.io.