What is SPIFFE and how does workload identity differ from network identity?
SPIFFE (Secure Production Identity Framework for Everyone) is a set of open specifications for giving every running workload a cryptographically verifiable identity. SPIRE is its reference implementation. Five concepts cover most of it:
- Trust domain: the root of trust, usually one per organization or environment, such as
prod.example.com. Everything inside it is signed by the same authority. - SPIFFE ID: a URI of the form
spiffe://trust-domain/path, for examplespiffe://prod.example.com/ns/payments/sa/api. The path is yours to design. It names what the workload is, not where it runs. - SVID (SPIFFE Verifiable Identity Document): the credential that proves a SPIFFE ID. An X.509-SVID is a certificate with the ID in its URI SAN, which you use for mTLS. A JWT-SVID is a signed token with the ID in its
subclaim, for cases where TLS cannot carry identity end to end. - Trust bundle: the CA certificates and public keys used to verify SVIDs from a trust domain.
- Workload API: a local endpoint, typically a Unix domain socket, where a workload obtains its SVIDs and bundles. The workload presents no secret to get them, which removes the bootstrap credential problem.
Why not trust the network?
IP allowlists and hostnames break when pods reschedule, NAT rewrites addresses, or many services share a node. A compromised neighbor on a trusted subnet inherits that trust. Workload identity is bound to verifiable attributes of the process, so it follows the service across clusters and clouds.
This guide treats SPIRE as an identity system first and a certificate issuer second. Issuing certificates is the easy part. Deciding who gets which identity is the hard part. SPIRE suits teams running many services across clusters, clouds, or languages that need one consistent identity model.
Who should use SPIFFE and SPIRE?
SPIFFE and SPIRE fit organizations where service-to-service authentication has outgrown hand-managed credentials. The strongest signals are:
- Many services that call each other. The more pairs of callers and callees you have, the more a shared, automated identity model pays off compared with per-service certificates or API keys.
- Heterogeneous infrastructure. Multiple Kubernetes clusters, a mix of Kubernetes and VMs, or more than one cloud. SPIRE's node attestors let one identity scheme span all of them, and federation lets separate trust domains verify each other.
- Polyglot codebases. A single identity format works whether a service uses a native SPIFFE library or sits behind a proxy that consumes SVIDs.
- Requirements for mutual authentication and auditability. If you need to prove which workload called which, a verified SPIFFE ID in every request log is a direct answer.
- A history of leaked or expired credentials. Short-lived, automatically rotated SVIDs remove long-lived secrets from images, config files and CI variables.
Within those organizations, responsibilities usually split three ways:
- Platform or infrastructure teams run the SPIRE Server and Agents, choose node attestors, and own availability and upgrades.
- Security teams design the SPIFFE ID naming scheme, review registration entries, and define which IDs may call which services.
- Service developers consume identity through a library or proxy and maintain the allowlist of callers for their own service.
If none of these signals apply, see the section on when to avoid SPIRE below.
How does it work? SPIRE Server, Agent, and the two stages of attestation
SPIRE splits the job into two components. The SPIRE Server is the signing authority: it holds the CA keys (or chains to an upstream CA) and stores registration entries that map workload properties to SPIFFE IDs. The SPIRE Agent runs on every node and exposes the Workload API over a Unix domain socket. A workload connects to that socket with no token, password, or certificate. This removes the bootstrap secret problem: nothing has to be baked into an image or injected at deploy time, because identity comes from where and how the process runs.
In short, it works in two stages. First the Agent proves which node it is on (node attestation). Then, for each process that connects to the socket, the Agent inspects the process and decides which identity it qualifies for (workload attestation). The Server never trusts what a workload says about itself; it trusts only what the Agent and the platform can verify.
Node attestation
When an Agent starts, it has to prove which node it is on. On Kubernetes, the Agent presents a projected service account token, and the Server validates it against the cluster's API server. On cloud VMs, the Agent presents the provider's signed instance identity document, and the Server checks the provider's signature. If the check passes, the Agent receives its own SVID and a set of node selectors.
Workload attestation
When a process calls the socket, the Agent asks the kernel for the caller's PID. It then gathers selectors such as unix:uid:1001 or, by querying the local kubelet, k8s:ns:payments and k8s:sa:checkout. The workload cannot assert its own selectors, so it cannot claim an identity it does not have.
End-to-end flow
- The Agent attests the node and the Server returns an Agent SVID.
- The Server sends the Agent the registration entries that apply to that node.
- A workload connects to the socket and the Agent attests it.
- If the workload's selectors match an entry, the Agent returns an SVID and trust bundle that were signed in advance and are held in its cache.
+----------------------------------------------------------------------+
| SPIRE Server |
| [ CA keys or upstream CA ] [ registration entries ] |
| signing authority entries: selectors -> SPIFFE ID |
+----------------------------------------------------------------------+
^ |
| (1) node attestation evidence: | (1) Agent SVID + selectors
| projected SA token (k8s) or | (2) registration entries
| cloud instance identity doc | for this node
| v
+----------------------------------------------------------------------+
| Node |
| +----------------------------------------------------------------+ |
| | SPIRE Agent (holds Agent SVID) | |
| | cache: pre-signed SVIDs + trust bundle, per matching entry | |
| | (3) attest caller: PID from kernel, then gather selectors | |
| | unix:uid:1001 k8s:ns:payments k8s:sa:checkout | |
| | (k8s selectors via query to local kubelet) | |
| | [ Workload API: Unix domain socket ] | |
| +----------------------------------------------------------------+ |
| ^ | |
| | (3) connect: no token, | (4) SVID + trust bundle|
| | password, or cert v |
| +----------------------------------------------------------------+ |
| | Workload process (e.g. payments/checkout) | |
| | uses SVID for mTLS; validates peers against trust bundle | |
| +----------------------------------------------------------------+ |
+----------------------------------------------------------------------+
SPIRE issuance flow: the Agent proves its node to the Server, receives its own SVID and the registration entries for that node, then attests each workload that connects over the Unix domain socket and returns a cached SVID and trust bundle when the workload's selectors match an entry.
How do you write SPIRE registration entries that issue identity to the right workloads?
An entry is a rule with three parts: the SPIFFE ID to issue, the parent ID that scopes which agents may serve it, and the selectors a workload must match. With spire-server entry create, these map to -spiffeID, -parentID and one or more -selector flags. A workload must match every selector on the entry, so each added selector narrows who qualifies.
Name identities after stable attributes
Build IDs from attributes that stay the same across restarts and that an attacker cannot easily set. In Kubernetes, use namespace plus service account, for example spiffe://example.org/ns/payments/sa/billing. Pod names change on every rollout, and anyone who can create pods in a namespace can choose a pod's name. Service accounts are controlled by RBAC.
| Selector basis | Stable across rollouts | Who controls it | Fit for identity |
|---|---|---|---|
k8s:pod-name |
No | Anyone who can create pods | Poor |
k8s:ns alone |
Yes | Namespace admins | Too broad |
k8s:ns + k8s:sa |
Yes | RBAC on service accounts | Good default |
Parent and child entries
A workload entry's parent is either one agent's SPIFFE ID or a node alias. A node alias is an entry created with -node that groups agents by their node selectors, such as the cluster name from k8s_psat. Pointing a workload entry at an alias lets any matching agent serve it.
Scope matters here. A broad alias, or weak node attestation, lets an untrusted node join the alias and fetch privileged SVIDs. A single-selector entry like k8s:ns:prod gives that identity to every pod in the namespace.
Verify
Confirm what the server will issue with spire-server entry show, and check which agents are attested with spire-server agent list. Then, from inside the workload, run spire-agent api fetch x509 to see the SVID it actually receives.
spire-server entry create \
-node \
-spiffeID spiffe://example.org/k8s-cluster/prod-cluster \
-selector k8s_psat:cluster:prod-cluster \
-selector k8s_psat:agent_ns:spire \
-selector k8s_psat:agent_sa:spire-agent
spire-server entry create \
-parentID spiffe://example.org/k8s-cluster/prod-cluster \
-spiffeID spiffe://example.org/ns/payments/sa/billing \
-selector k8s:ns:payments \
-selector k8s:sa:billing
spire-server entry show -spiffeID spiffe://example.org/ns/payments/sa/billing
spire-server entry show -parentID spiffe://example.org/k8s-cluster/prod-cluster
spire-server agent list
spire-agent api fetch x509 -socketPath /run/spire/sockets/agent.sock
Creates a cluster-scoped node alias and a workload entry keyed on namespace plus service account, then checks the result with spire-server entry show, spire-server agent list and spire-agent api fetch x509.
How do you implement service to service mTLS with SPIFFE IDs and authorization?
Once that SVID appears, the workload can use it. In Go, go-spiffe gives you an X.509 source connected to the Workload API socket. The source holds the current SVID and trust bundle in memory and swaps in renewed certificates as the agent pushes them, so the process never reads key files from disk or restarts to rotate. Build the server's TLS config and the client's TLS config from the same source. Each side then presents its own SVID and checks the peer's chain against the trust bundle.
Chain validation answers only one question: does this certificate come from my trust domain? Every workload you register in that domain passes the check, so membership grants no permission. Authorization is a separate step. The client should require the exact SPIFFE ID of the server it expects, such as spiffe://prod.example/payments. The server should accept only an allowlist of caller IDs. go-spiffe has authorizer helpers for one ID, a set of IDs, or trust-domain membership. Use membership only for endpoints that every workload in the domain is meant to reach, such as health checks.
Native library vs. sidecar proxy
| Factor | Native library | Sidecar proxy |
|---|---|---|
| Code changes | TLS config and authorization in each service | None. The app talks plaintext to localhost |
| Language coverage | Limited to languages with a mature SPIFFE library | Any language |
| Latency | No extra hop | Extra local hop per request |
| Resource cost | Shared with the app | Separate CPU and memory per pod |
| Debuggability | Peer ID is visible in app logs and traces | Identity sits in proxy logs, away from app context |
// Go, using github.com/spiffe/go-spiffe/v2. Server and client are shown together for brevity.
func main() {
ctx := context.Background()
// One X509Source per process. It streams SVID and bundle updates from the
// SPIRE agent, so rotation happens in memory with no files and no restarts.
source, err := workloadapi.NewX509Source(ctx, workloadapi.WithClientOptions(
workloadapi.WithAddr("unix:///run/spire/sockets/agent.sock")))
if err != nil {
log.Fatal(err)
}
defer source.Close()
// Server (payments): chain validation proves trust-domain membership only.
// The allowlist is what grants permission to call this service.
callers := tlsconfig.AuthorizeOneOf(
spiffeid.RequireFromString("spiffe://prod.example/checkout"),
spiffeid.RequireFromString("spiffe://prod.example/refunds"),
)
srv := &http.Server{
Addr: ":8443",
TLSConfig: tlsconfig.MTLSServerConfig(source, source, callers),
Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
// Log the verified caller ID so it shows up in app logs and traces.
id, _ := x509svid.IDFromCert(r.TLS.PeerCertificates[0])
log.Printf("request from %s", id)
}),
}
// Empty cert/key paths: certificates come from TLSConfig, not disk.
go func() { log.Fatal(srv.ListenAndServeTLS("", "")) }()
// Client (checkout): require the exact server ID, not just any workload in the domain.
payments := spiffeid.RequireFromString("spiffe://prod.example/payments")
client := &http.Client{Transport: &http.Transport{
TLSClientConfig: tlsconfig.MTLSClientConfig(source, source, tlsconfig.AuthorizeID(payments)),
}}
if _, err := client.Get(""); err != nil {
log.Printf("call failed: %v", err)
}
}
Go code using go-spiffe v2 that builds both the server and client mTLS configs from one auto-rotating X509Source, with an allowlist of caller IDs on the server and an exact-ID check on the client.
Short-lived SVIDs, rotation, and keeping SPIRE available
A stolen SVID private key is only useful until the certificate expires. With TTLs measured in minutes or hours, an attacker who extracts a key from a compromised pod has a short window, and there is no revocation list to distribute. The SPIRE Agent renews SVIDs well before expiry and pushes them to workloads over the Workload API stream. Libraries built on that API swap certificates in memory, so no restart is needed.
Rotation only helps if the application uses the new credential. A service that reads a certificate file once at startup will keep presenting the old one until the handshake fails. To confirm reloads, log the serial number and expiry of the certificate each peer presents, then check that the serials change over a day. Alert on any connection that offers a certificate close to its expiry.
Shorter TTLs reduce the compromise window but add costs:
- The server performs more signing operations.
- Clock skew between nodes matters more.
- A brief loss of connectivity between agent and server becomes an outage sooner.
Illustrative estimate: Assume a 1-hour SVID TTL and renewal at half-life. If the server fails just before a scheduled renewal, workloads have about 30 minutes before their certificates expire. If it fails just after a renewal, they have close to 60 minutes. New pods cannot get an identity at all during the outage.
Treat the SPIRE Server as critical infrastructure. Run multiple replicas on a durable shared datastore, and restore from backup on a regular schedule to prove the backups work. Root and intermediate CA rotation needs particular care. Distribute the new trust bundle to every agent and federated domain before anything signs with the new key, and keep the old key trusted until every SVID it issued has expired.
When should you use JWT-SVIDs, and what are the alternatives to SPIFFE mTLS?
X.509-SVIDs only help when the TLS connection runs end to end between the two workloads. If an L7 proxy, API gateway or load balancer terminates TLS in between, the upstream service sees the proxy's certificate and loses the caller's identity. JWT-SVIDs solve this because the identity rides in an application header and survives TLS termination. They also suit workloads that cannot hold a client certificate, such as some managed runtimes or legacy HTTP clients.
A JWT-SVID is a bearer token, so anyone who obtains it can use it until it expires. Keep lifetimes short, and request each token with the narrowest aud value, ideally one per destination service. Receivers must reject any token whose audience does not name them. Otherwise, a token stolen from one service can be replayed against every other service. Validate the signature against the trust domain's JWT bundle, check expiry, and still require TLS on every hop so the token is never sent in plaintext.
| Approach | Identity binding | Rotation | Portability | Operational burden |
|---|---|---|---|---|
| SPIFFE/SPIRE | Attested workload properties | Automatic, short-lived | Any platform, federation | Run and keep SPIRE available |
| Manual internal PKI | Whoever holds the key file | Manual or scripted, often long-lived | High, but ad hoc | Issuance, revocation, expiry tracking |
| Cloud workload identity | Platform-attested | Automatic | Single provider | Low inside the provider |
| Service mesh built-in identity | Platform service account | Automatic | Within the mesh | Mesh upgrades, sidecar lifecycle |
| Shared API keys/tokens | Whoever has the secret | Manual, rarely done | High | Secret distribution, leak response |
#!/usr/bin/env bash
set -euo pipefail
SOCKET=/run/spire/sockets/agent.sock
AUDIENCE=spiffe://example.org/billing-api
spire-agent api fetch jwt \
-audience "$AUDIENCE" \
-socketPath "$SOCKET"
TOKEN='<jwt-svid-from-fetch-output>'
curl --fail \
-H "Authorization: Bearer ${TOKEN}"
spire-agent api validate jwt \
-audience "$AUDIENCE" \
-svid "$TOKEN" \
-socketPath "$SOCKET"
A caller fetches a JWT-SVID scoped to a single audience and sends it over TLS, and the receiver validates the signature, expiry and audience through its local SPIRE agent.
How can SPIFFE and SPIRE save engineering time?
The time savings come from removing recurring manual work around service credentials, not from making any single request faster. The main sources are:
- No manual certificate issuance or renewal. Agents renew SVIDs automatically and libraries reload them in memory. Nobody files tickets for new certificates, tracks expiry dates in a spreadsheet, or schedules restarts to pick up a renewed key.
- Fewer expiry-driven incidents. Long-lived certificates tend to expire unnoticed and cause outages that take time to diagnose. With short TTLs and automatic rotation, expiry becomes a monitored condition instead of a surprise.
- No secret distribution. Workloads get identity from the Workload API, so there are no keys to copy into images, CI variables, or secret stores, and no audits to find where a key ended up.
- Cheaper revocation. Removing a workload's access means deleting or changing its registration entry and waiting for its short-lived SVIDs to expire. Compare that with rotating a shared API key across every service that holds it.
- Simpler onboarding. A new service needs a registration entry and a caller allowlist. The identity model, rotation and validation are already in place.
- Faster debugging and audits. Every request can be logged with a verified caller SPIFFE ID, so questions like "which service sent this?" are answered from logs rather than by tracing IP addresses through NAT and rescheduled pods.
Illustrative estimate: Assume an organization with 40 services, each holding one manually managed certificate renewed once a year, with each renewal taking 2 engineer-hours of issuance, deployment and coordination. That is about 80 hours a year. Assume also 2 shared-credential rotations a year, each touching 10 services at 1 hour per service, adding 20 hours. The assumed total of about 100 hours a year of manual credential work largely goes away. Against that, you must budget time for running SPIRE: upgrades, monitoring, datastore backups and incident response. Whether the trade is worth it depends on how many services you run and how often credentials change. With these assumed inputs, the savings grow with the number of services while SPIRE's operating cost stays roughly flat, which is why SPIRE tends to pay off at larger service counts.
When should you avoid SPIRE, and how do you roll it out without breaking production?
SPIRE is critical infrastructure, and it only pays off when the identity problem is bigger than the cost of running it. You can usually skip it in these cases:
- You have a handful of services. A few long-lived certificates managed by hand may be cheaper overall.
- You run on a single platform whose native workload identity already covers your traffic.
- Most of your calls go to legacy or third-party systems that cannot present or verify SVIDs. You would end up maintaining two trust systems.
- No team can own SPIRE Server availability, upgrades, and incident response.
The cost is real. You have to integrate the Workload API through libraries or a proxy. You also have to debug failures that look identical at the TLS layer. An expired SVID, a missing registration entry, and a stale trust bundle all show up as a generic handshake error. The payoff is that nobody distributes secrets or renews certificates manually anymore, and revoking a workload means deleting an entry instead of rotating a shared key everywhere.
A rollout that doesn't break production
- Run permissive. Issue SVIDs and accept mTLS connections, but keep existing authentication as the deciding check. Log the peer SPIFFE ID on every request.
- Monitor. Alert on SVID time-to-expiry, agent attestation failures, and connections still arriving without an SVID. These logs show you which callers will break under enforcement.
- Enforce. Require mTLS one service at a time, starting with low-risk paths.
- Tighten. Replace "any ID in the trust domain" with per-ID allow lists. Remove the old credentials only after that.
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 spiffe, 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.
- Reviewers see the exact diff and the list of affected services up front, so approval is a decision rather than an investigation.
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.
- Per-service approve/reject means a bad shared value can be refused where it would break something, before it is live.
- 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.