Use Vault Proxy as an API proxy

Vault Proxy's API Proxy functionality allows you to use Vault Proxy's API as a proxy for Vault's API.

Functionality

The listener stanza for Vault Proxy configures a listener for Vault Proxy. If its role is not set to metrics_only, it will act as a proxy for the Vault server that has been configured in the vault stanza of Proxy. This enables access to the Vault API from the Proxy API, and can be configured to optionally allow or force the automatic use of the Auto-Auth token for these requests, as described below.

If a listener has been configured alongside a cache stanza, the API Proxy will first attempt to utilize the cache subsystem for qualifying requests, before forwarding the request to Vault. See the caching docs for more information on caching.

Using Auto-Auth token

Vault Proxy allows for easy authentication to Vault in a wide variety of environments using Auto-Auth. By setting the use_auto_auth_token (see below) configuration, clients will not be required to provide a Vault token to the requests made to the Proxy. When this configuration is set, if the request doesn't already bear a token, then the auto-auth token will be used to forward the request to the Vault server. This configuration will be overridden if the request already has a token attached, in which case, the token present in the request will be used to forward the request to the Vault server.

Forcing Auto-Auth token

Vault Proxy can be configured to force the use of the auto-auth token by using the value force for the use_auto_auth_token option. This configuration overrides the default behavior described above in Using Auto-Auth Token, and instead ignores any existing Vault token in the request and instead uses the auto-auth token.

Configuration (`api_proxy`)

The top level api_proxy block has the following configuration entries:

use_auto_auth_token (bool/string: false) - If set, the requests made to Proxy without a Vault token will be forwarded to the Vault server with the auto-auth token attached. If the requests already bear a token, this configuration will be overridden and the token in the request will be used to forward the request to the Vault server. If set to "force" Proxy will use the auto-auth token, overwriting the attached Vault token if set.

Note: When using the proxy's auto-auth token with the use_auto_auth_token configuration, one proxy per application is very strongly recommended, as Vault will unable to distinguish requests coming from multiple applications through a single proxy. In situations where a single proxy is shared by multiple applications, setting use_auto_auth_token to false (the default) is recommended.

prepend_configured_namespace (bool: false) - If set, when Proxy has a namespace configured, such as through the Vault stanza, all requests proxied to Vault will have the configured namespace prepended to the namespace header. If Proxy's namespace is set to ns1 and Proxy is sent a request with the namespace ns2, the request will go to the ns1/ns2 namespace. Likewise, if Proxy is sent a request without a namespace, the request will go to the ns1 namespace. In essence, what this means is that all proxied requests must go to the configured namespace or to its child namespaces.

The following two api_proxy options are only useful when making requests to a Vault Enterprise cluster, and are documented as part of its Eventual Consistency page.

enforce_consistency (string: "never") - Set to one of "always" or "never".
when_inconsistent (string: optional) - Set to one of "fail", "retry", or "forward".

Example configuration

Here is an example of a listener configuration alongside api_proxy configuration to force the use of the auto_auth token and enforce consistency for a proxy dedicated to a single application.

# Other Vault Proxy configuration blocks# ... api_proxy {  use_auto_auth_token = "force"  enforce_consistency = "always"} listener "unix" {    address = "/var/run/vault-proxy.sock}