Vault Proxy static secret caching
Appropriate Vault Enterprise license required
Use static secret caching with Vault Proxy to cache KVv1 and KVv2 secrets to minimize requests made to Vault and provide resilient connections for clients.
Vault Proxy utilizes the Enterprise only Vault event notification system feature for cache freshness. As a result, static secret caching can only be used with Vault Enterprise installations.
Step 1: Subscribe Vault Proxy to KV events
Vault Proxy uses Vault events and auto-auth to monitor secret status and make appropriate cache updates.
Enable auto-auth.
Create an auto-auth token with permission to subscribe to KV event updates with the Vault event notification system. For example, to create a policy that grants access to static secret (KVv1 and KVv2) events, you need permission to subscribe to the
events
endpoint, as well as thelist
andsubscribe
permissions on KV secrets you want to get secrets from:
Subscribing to KV events means that Proxy receives updates as soon as a secret changes, which reduces staleness in the cache. Vault Proxy only checks for a secret update if an event notification indicates that the related secret was updated.
Step 2: Ensure tokens have capabilities-self
access
Tokens require update
access to the
sys/capabilies-self
endpoint to
request cached secrets. Vault tokens receive update
permissions
by default. If you have modified
or removed the default policy, you must explicitly create a policy with the
appropriate permissions. For example:
Step 3: Configure an appropriate refresh interval
By default, Vault Proxy refreshes tokens every five minutes. You can change the
default behavior and configure Proxy to verify and update cached token
capabilities with the static_secret_token_capability_refresh_interval
parameter in the cache
configuration stanza. For example, to set a refresh
interval of one minute:
Functionality
With static secret caching, Vault Proxy caches GET
requests for KVv1 and KVv2
endpoints.
When a client sends a GET
request for a new KV secret, Proxy forwards the
request to Vault but caches the response before forwarding it to the client. If
that client makes subsequent GET
requests for the same secret, Vault Proxy
serves the cached response rather than forwarding the request to Vault.
Similarly, when a token requests access to a KV secret, it must complete a
success GET
request. If the request is successful, Proxy caches the fact that
the token was successful in addition to the result. Subsequent requests by the
same token can then access this secret from the cache instead of Vault.
Vault Proxy uses the event notification system to keep the cache up to date. It monitors the KV event feed for events related to any secret currently stored in the cache, including modification events like updates and deletes. When Proxy detects a change in a cached secret, it will update or evict the cache entry as appropriate.
Vault Proxy also checks and refreshes the access permissions of known tokens
according to the window set with static_secret_token_capability_refresh_interval
.
By default, the refresh interval is five minutes.
Every interval, Proxy calls sys/capabilies-self
on
behalf of every token in the cache to confirm the token still has permission to
access the cached secret. If the result from Vault indicates that permission (or
the token itself) was revoked, Proxy updates the cache entry so that the affected
token can no longer access the relevant paths from the cache. The refresh interval
is essentially the maximum period after which permission to read a KV secret is
fully revoked for the relevant token.
For token refresh to work, any token that will access the cache also needs
update
permission for sys/capabilies-self
.
Having update
permission for the token lets Proxy test capabilities for the
token against multiple paths with a single request instead of testing for a 403
response for each path explicitly.
Refresh is per token, not per secret
If Proxy's API proxy is configured to use auto-authentication for tokens, and all requests that pass through Vault Proxy use the same token, Proxy only makes a single request to Vault every refresh interval, no matter how many secrets are currently cached.
When static secret caching is enabled, Proxy returns HIT
or MISS
in the X-Cache
response header for requests so client can tell if the response was served from
the cache or forwarded from Vault. In the event of a hit, Proxy also sets the
Age
header to indicate, in seconds, how old the cache entry is.
Old does not mean stale
The fact that a cache entry is old, does not necessarily mean that the
information is out of date. Vault Proxy continually monitors KV events for
updates. A large value for Age
may simply mean that the secret has not been
rotated recently.
Configuration
The top level cache
block has the following configuration entries relating to static secret caching:
cache_static_secrets
(bool: false)
- Enables static secret caching when set totrue
. Whencache_static_secrets
andauth_auth
are both enabled, Vault Proxy serves KV secrets directly from the cache to clients with sufficient permission.static_secret_token_capability_refresh_interval
(duration: "5m", optional)
- Sets the interval as a duration format string at which Vault Proxy rechecks the permissions of tokens used to access cached secrets. The refresh interval is the maximum period after which permission to read a cached KV secret is fully revoked. Ignored whencache_static_secrets
isfalse
.
Example configuration
The following example Vault Proxy configuration:
- Defines a TCP listener (
listener
) with TLS disabled. - Forces clients using API proxy (
api_proxy
) to identify with an auto-auth token. - Configures auto-authentication (
auto-auth
) forapprole
. - Enables static secret caching with
cache_static_secrets
. - Sets an explicit token capability refresh window of 1 hour with
static_secret_token_capability_refresh_interval
.