SPIFFE auth method
Enterprise
Appropriate Vault Enterprise license required
The spiffe auth method lets workloads authenticate to Vault using SPIFFE
Verifiable Identity Documents (SVIDs). You can choose either X.509 certificates
or JWTs whose trust comes from a configured trust bundle. Unlike
platform-specific auth methods (Kubernetes, AWS, Azure), SPIFFE auth works the
same way regardless of what the workload is running on: bare metal, virtual
machines (VMs), or multi-cloud Kubernetes clusters.
If you are not familiar with the SPIFFE framework, refer to the SPIFFE concepts documentation.
When to use SPIFFE auth with Vault
Use SPIFFE auth with Vault when:
- Your workloads span heterogeneous compute sources such as bare metal, VMs, or multiple clouds with no single platform-native identity issuer covering all workloads.
- You need mTLS-based identity (X.509-SVID), not just bearer JWTs. For example, if you require Vault access to fit into a broader zero-trust or service-mesh identity model rather than a single auth token.
- You already run SPIRE or a service that generates SVIDs for workload identity and want Vault to consume identity from that same trust domain instead of maintaining a separate auth scheme.
- You need identity that federates across organizational or cloud boundaries through a standardized trust-domain model.
For user-based, interactive or browser-based authentication, refer to the JWT/OIDC auth method.
Understanding the difference between the SPIFFE auth method and the SPIFFE secrets engine helps you choose the right integration for your use case.
SPIFFE auth vs. SPIFFE secrets engine
- Use SPIFFE auth (
auth/spiffe) when you have SPIRE (or another SPIFFE issuer) running and want to authenticate to Vault using a SVID. - Use the SPIFFE secrets engine (
secrets/spiffe) when you want to generate a SPIFFE ID and SVID with an existing Vault auth method (Kubernetes, AppRole, AWS, and others). Refer to the SPIFFE secrets engine docs for details.
How SPIFFE auth works
When implementing SPIFFE with Vault, the key architectural distinction is which system generates the workload identity versus which system validates it.
Vault cannot issue a SPIFFE identity to a workload before the workload authenticates. A SPIFFE control plane (a SPIRE Agent running on the host node, or a service mesh) must attest the workload and issue an SVID first.
Vault is the consumer, not an issuer of the SVID. The auth/spiffe plugin allows
Vault to accept and validate identities generated by an external SPIFFE authority
(such as SPIRE), it does not generate SPIFFE identities itself.
[ External SPIFFE Issuer ] ───(0. Fetch trust bundle)───────> [ HashiCorp Vault ]
(e.g., SPIRE Agent/Server) (validates SVIDs
| against bundle)
│ ▲
│ 1. Issue SVID │
▼ │
[ Workload ] ─────────────(2. Present SVID to login)─────────────────┘
Supported trust bundle formats
Vault accepts two types of SVIDs:
- X.509-SVIDs (mTLS): The client presents a client certificate
containing a SPIFFE URI (e.g.,
spiffe://example.org/ns/prod/sa/payment-service) in its SAN field. Vault validates the certificate against the configured trust bundle. - JWT-SVIDs: The client fetches a short-lived JWT from its local SPIFFE
Workload API and sends it as a bearer token. Vault validates the signature
against the trust bundle's JWKS and checks the
audclaim against the mount's audience allowlist.
The trust bundle's file format determines which SVID types Vault can validate. A bundle in the wrong format will not validate the other type, even if everything else is configured correctly.
| Bundle format | Contains | Validates |
|---|---|---|
| JWKS document | X.509 CA certificate(s) and JWT signing key(s) | X.509-SVIDs and JWT-SVIDs |
| PEM-encoded X.509 certificate | X.509 CA certificate only | X.509-SVIDs only |
The SVID you choose maps directly to the profile parameter when you configure
the SPIFFE auth method in Vault. Each type has different use cases and trade-offs.
| Profile | Bundle format | SVID types supported | How Vault fetches the bundle | Best for |
|---|---|---|---|---|
static (bundle = PEM) | PEM | X.509-SVIDs only | Pasted in directly, no fetch | Air-gapped/no-network-dependency requirement, JWT-SVID not needed, strict change control on trust-anchor updates |
static (bundle = JWKS) | JWKS | X.509-SVIDs and JWT-SVIDs | Pasted in directly, no fetch | Same as above, but both SVID types needed |
https_web_pem | PEM | X.509-SVIDs only | Auto-fetched over HTTPS, validated against a CA (system trust store or a custom endpoint_root_ca_truststore_pem) | Vault can reach the endpoint, JWT-SVID not needed |
https_web_bundle | JWKS | X.509-SVIDs and JWT-SVIDs | Auto-fetched over HTTPS, validated against a CA (system trust store or a custom endpoint_root_ca_truststore_pem) | Federating with a SPIFFE-compliant issuer other than SPIRE, or a SPIRE server specifically exposing an https_web-type Federation endpoint |
https_spiffe_bundle | JWKS | X.509-SVIDs and JWT-SVIDs | Auto-fetched; endpoint validated by matching a specific SPIFFE ID (endpoint_spiffe_id) rather than a CA chain | The standard choice for federating with a SPIRE upstream — what most setups should use by default |
If Vault is behind a load balancer or reverse proxy, refer to load balancer and proxy considerations before configuring the auth method. Where TLS terminates determines whether X.509-SVID auth is viable as documented, or whether you need to rely on JWT-SVIDs instead.