Enable and use the SPIFFE secrets engine

The spiffe secrets engine mints SPIFFE JSON Web Token SPIFFE Verifiable Identity Documents (JWT-SVIDs) using a template that can interpolate identity information about the requesting entity.

Enable SPIFFE secrets engine

Each SPIFFE backend instance has a single trust domain. The plugin uses roles to define templates that determine the claims in the minted JWTs. To follow this example, use a token with permission to enable secrets engines and write to the spiffe/ mount.

1. Enable the SPIFFE secrets engine.

   $ vault secrets enable spiffe
   Success! Enabled the spiffe secrets engine at: spiffe/
   

2. Configure the trust domain.

   $ vault write spiffe/config trust_domain=example.org
   Key                            Value
   ---                            -----
   bundle_refresh_hint            3600
   jwt_issuer_url                 n/a
   jwt_oidc_compatibility_mode    false
   jwt_signing_algorithm          RS256
   key_lifetime                   86400
   trust_domain                   example.org
   

3. Create a role.

   $ vault write spiffe/role/role1 template='{"sub": "spiffe://example.org/workload"}' ttl=5m
   Key              Value
   ---              -----
   name             role1
   template         {"sub": "spiffe://example.org/workload"}
   ttl              300
   use_jti_claim    false
   

Usage

Minting a JWT-SVID requires specifying an audience. Vault returns a signed token that your workload can present to the target service.

$ vault write spiffe/role/role1/mintjwt audience=my-aud
Key            Value
---            -----
token          eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Integrate with the SPIFFE auth method on another Vault cluster

The SPIFFE secrets engine has a trust_bundle/web endpoint that serves the trust bundle. Clients can call the trust endpoint to fetch the public keys needed to validate JWTs minted by the plugin. This allows workloads to use minted JWT-SVIDs to authenticate to another Vault cluster running the SPIFFE auth method.

Integrate with OIDC

The SPIFFE secrets engine supports JWT-SVIDs that work with OIDC providers.

Set jwt_oidc_compatibility_mode=true in the secrets engine configuration.

$ vault write spiffe/config \
    trust_domain=example.org \
    jwt_oidc_compatibility_mode=true

Setting jwt_oidc_compatibility_mode=true limits the SVID to 255 characters, which is the limit for JWT sub claims in OIDC.

There are also two endpoints that allow OIDC providers to validate the JWTs Vault mints:

• .well-known/openid-configuration: Returns OIDC discovery metadata for the mount.
• .well-known/keys: Returns the JSON Web Key Set (JWKS) that contains the public signing keys for issued tokens.

API

The SPIFFE secrets engine has a full HTTP API. Refer to the SPIFFE secrets engine API documentation for more details.

Terraform

You can use Terraform to manage the SPIFFE secrets engine declaratively. Use the vault_mount resource to enable the SPIFFE secrets engine and the vault_spiffe_secret_backend_config resource to manage the configuration.

• Vault mount backend resource
• Vault SPIFFE secret backend config resource
• Vault SPIFFE secret backend role resource

Next steps

• Refer to the SPIFFE secrets engine overview for architecture, use cases, and feature details.
• Refer to the SPIFFE secrets engine API documentation for endpoint details.