SPIFFE auth method

The spiffe auth method lets you configure authentication using JWT or x.509 based SPIFFE SVIDs whose trust can be rooted within a configured trust bundle.

To use the SPIFFE plugin with x.509 SPIFFE IDs, you must have tls_disable and tls_disable_client_certs set to false in your Vault configuration to allow the certificates through TLS.

Configuration

Each SPIFFE backend instance has a single trust domain and an associated trust bundle and a role-level configuration that maps SPIFFE workload IDs to Vault token policies. Vault accepts trust bundles provided as part of the configuration or fetched from a remote endpoint over HTTPS.

Integrate with SPIRE

If you use SPIRE to issue SPIFFE SVIDs, you can configure Vault to fetch the trust bundle directly from the SPIRE Federation API if you use https_web and https_spiffe Federation endpoints.

JWT SPIFFE SVID requirements

To use JWT based SPIFFE SVIDs, you must include the Authorization header in the set of passthrough request headers for the SPIFFE plugin so clients can provide the SVID in the Authorization header as a Bearer token. For example:

Authorization: Bearer <svid-jwt>

When enabling the SPIFFE auth method, you can specify the passthrough Use the -passthrough-request-headers flag when you enable or tune the SPIFFE plugin to add Authorization to the set of allowed passthrough headers.

For example, to configure the headers when you mount the plugin, use -passthrough-request-headers with vault auth enable:

$ vault auth enable -passthrough-request-headers="Authorization" spiffe

Or, to configure the headers on an existing mount, use -passthrough-request-headers with vault auth tune:

$ vault auth tune -passthrough-request-headers="Authorization" spiffe

Provide valid audience values

When using JWT based SPIFFE SVIDs, you must configure the plugin with a list of allowable audience values and clients must set the audience parameter with one of the appropriate values. Vault allows any client with a matching element to authenticate. If the list of allowable values is empty, Vault denies all JWT based SVIDS.

Supported trust bundle formats

To use JWT and x.509 based SPIFFE IDs, the trust bundle must contain the X.509 certificate(s) and JWK key(s) within a JWKS document for static and fetched bundles.

To use a PEM encoded X.509 certificate, the trust bundle must provide a x.509 based SPIFFE ID.

Refreshing remote trust bundles

Vault caches trust bundles fetched from remote endpoints and refreshes the bundle periodically based on the provided refresh hint. If the bundle does not provide a refresh hint, Vault uses a default refresh interval of 1 hour.

The active node within a Vault cluster performs the initial fetch and subsequent refreshes on the trust bundle on behalf of all nodes in the cluster. But all active nodes on Performance replica clusters fetch and refresh the trust bundle independently.

You can force an immediate refresh by calling the configuration endpoint with an empty payload and read the details about a fetched trust bundle, including the last refresh time and calculated refresh interval by calling the read configuration endpoint.

Load balancing and proxying consideration

TLS terminates before client requests reach Vault when you use a reverse proxy or load balancer as your Vault server fronted. As a result, you must:

1. Configure your frontend to provide the validated client certificate in the request header.
2. Configure your Vault listener to accept the header provided by the frontend.
3. Ensure your frontend performs full TLS verification to the client to provide proper authentication security.
4. Ensure a secure connection between your frontend and Vault, ideally with Mutual TLS.

SPIFFE plugin API

The SPIFFE auth method has a full HTTP API. Refer to the SPIFFE auth API documentation for more details.