Skip to main content

Module 3: SPIFFE Fundamentals

The specification that defines how workload identity works

3 hours. 2 hands-on labs. Free course module.

Learning Objectives

  • Understand the SPIFFE specification and its components
  • Learn SPIFFE ID format and trust domains
  • Master X.509-SVIDs and JWT-SVIDs
  • Use the SPIFFE Workload API

Why This Matters

SPIFFE is the specification that every SPIRE deployment implements. Understanding SPIFFE means you can evaluate any workload identity solution — not just SPIRE — and make informed architecture decisions. This module teaches you the standard itself, so your knowledge transcends any single implementation.

SPIFFE IDENTITY ARCHITECTURETrust Domain: example.orgX.509-SVIDCertificate + Private KeyFor mTLS connectionsJWT-SVIDSigned JWT TokenFor HTTP APIsTrust BundleCA certificatesFor verificationSPIFFE Workload API (Unix Domain Socket)Workload AWorkload BWorkload C
Architecture diagram for Module 3: SPIFFE Fundamentals.

Lesson Content

SPIFFE (Secure Production Identity Framework For Everyone) is a set of open standards that define how workloads identify themselves to each other. It does not prescribe an implementation — it defines the what, and projects like SPIRE implement the how.

What Problems Does SPIFFE Solve?

Before SPIFFE, every organization invented its own way to identify services: custom PKI, Vault-issued secrets, Kubernetes service account tokens, cloud IAM roles, or plain shared passwords. None of these were interoperable, standardized, or designed for cross-platform workload identity. SPIFFE provides a universal identity format that works across Kubernetes, VMs, bare metal, and cloud providers.

SPIFFE Trust Domains

A trust domain is the root of trust for a set of workloads. It is identified by a domain name and corresponds to one SPIFFE identity authority (like a SPIRE server).

# Trust domain format:
spiffe://example.org

# All workloads in this trust domain share the same root CA
# Cross-trust-domain communication requires federation

SPIFFE IDs

A SPIFFE ID is a URI that uniquely identifies a workload within a trust domain:

# Format: spiffe://trust-domain/path

# Examples:
spiffe://example.org/ns/production/sa/api-server
spiffe://example.org/ns/staging/sa/web-frontend
spiffe://payments.example.org/region/us-east/service/processor

# The path is arbitrary but typically encodes:
# - Namespace
# - Service account
# - Environment
# - Region

SPIFFE Verifiable Identity Documents (SVIDs)

An SVID is the document that proves a workload’s identity. SPIFFE defines two formats:

X.509-SVID

An X.509 certificate with the SPIFFE ID in the URI SAN (Subject Alternative Name) field. Used for mTLS connections where both sides present certificates.

JWT-SVID

A signed JWT with the SPIFFE ID in the sub claim. Used for HTTP APIs where the identity is passed in a header rather than established at the TLS layer.

The SPIFFE Workload API

The Workload API is how workloads request and receive their identities. It is exposed as a Unix domain socket — no network communication, no credentials needed. The identity provider (like SPIRE Agent) authenticates the workload by inspecting the calling process (PID, user, container ID) and returns the appropriate SVID.

# The Workload API provides:
# 1. FetchX509SVID    - Get the workload's X.509 certificate
# 2. FetchJWTSVID     - Get a JWT token for the workload
# 3. FetchX509Bundles - Get trust bundles for verification
# 4. ValidateJWTSVID  - Validate a received JWT token

# No credentials needed to call the API!
# The Agent identifies the workload by its process attributes

Identity Lifecycle

Understanding the full lifecycle is critical for production operations:

  1. Workload Creation: A pod starts on a Kubernetes node
  2. Workload Attestation: SPIRE Agent inspects the process and matches it to a registration entry
  3. SVID Issuance: SPIRE Server signs and issues an X.509 certificate or JWT
  4. Identity Active: The workload uses its SVID for mTLS and authentication
  5. Automatic Rotation: Before the SVID expires, SPIRE issues a new one transparently
  6. Workload Termination: When the pod is deleted, the SVID naturally expires (short-lived = no revocation needed)

This lifecycle is fully automatic. No human intervention. No certificate renewal tickets. No expiry alerts. SPIRE handles it end-to-end.

SPIFFE Federation

When workloads in different trust domains need to communicate, they use federation. Each trust domain shares its trust bundle (CA certificates) with the other, allowing cross-domain SVID verification without merging the domains.

Real-World Use Cases

  • Multi-cloud identity — same SPIFFE IDs work across AWS, GCP, Azure
  • Kubernetes to VM communication — heterogeneous environments sharing trust
  • Cross-organization federation — partner services verifying each other
  • Service mesh identity layer — SPIFFE as the foundation for Istio/Linkerd identity

Common Mistakes

  • Incorrect trust domain naming — using internal hostnames instead of stable domain names
  • Hardcoding SPIFFE IDs in application code instead of using selectors
  • Using JWT-SVID where X.509-SVID is required (e.g., for mTLS)
  • Not planning SPIFFE ID path schemas before deployment — hard to change later
  • Confusing SPIFFE (the spec) with SPIRE (the implementation)

Think Like an Engineer

  • How should you name your trust domains for a multi-cluster, multi-cloud organization?
  • When should you use X.509-SVIDs vs JWT-SVIDs for a given service interaction?
  • How would you design SPIFFE ID paths that support both Kubernetes and VM workloads?
  • What happens when a trust domain needs to be renamed or split?

Career Relevance

SPIFFE is a CNCF standard adopted by Bloomberg, Uber, Pinterest, and ByteDance. Understanding the specification — not just the implementation — marks the difference between an engineer who follows tutorials and one who designs identity architectures.

Key Terms

Trust Domain
The root of trust, identified by a domain name, corresponding to one identity authority
SPIFFE ID
A URI (spiffe://trust-domain/path) uniquely identifying a workload
X.509-SVID
Certificate-based identity document for mTLS
JWT-SVID
Token-based identity document for HTTP APIs
Workload API
Unix domain socket API for workloads to request identities
Federation
Cross-trust-domain trust via bundle exchange

Hands-On Labs

  1. Exploring SPIFFE IDs

    Understand SPIFFE ID format and naming conventions.

    • Design SPIFFE ID schemas for a microservice application
    • Map Kubernetes namespaces and service accounts to SPIFFE ID paths
    • Validate SPIFFE IDs against the specification

    View lab files on GitHub

  2. Working with SVID Formats

    Inspect and compare X.509-SVIDs and JWT-SVIDs.

    • Generate a sample X.509-SVID and inspect its SAN field
    • Generate a sample JWT-SVID and decode its claims
    • Compare the two formats and discuss when to use each

    View lab files on GitHub

Key Takeaways

  • SPIFFE is a specification, not an implementation — SPIRE is the implementation
  • Trust domains are the root of trust, identified by a domain name
  • SPIFFE IDs are URIs: spiffe://trust-domain/path
  • X.509-SVIDs are for mTLS, JWT-SVIDs are for HTTP APIs
  • The Workload API uses Unix domain sockets — no credentials needed
  • Federation enables cross-trust-domain communication