vault What is Auto authentication Use auto authentication with Vault Agent or Vault Proxy to simplify client layout docs authentication to Vault in a variety of environments page title What is Auto authentication

Answer:
---
layout: docs
page_title: What is Auto-authentication?
description: >-
  Use auto-authentication with Vault Agent or Vault Proxy to simplify client
  authentication to Vault in a variety of environments.
---

# What is Auto-authentication?

Auto-authentication simplifies client authentication in a wide variety of
environments. The following Vault tools come with auto-authentication built in:

- Vault Agent
- Vault Proxy

## Methods and sinks

Auto-auth consists of two parts:

- a **method** - the desired authentication method for the current environment
- a **sink** - the location where tools save tokens when the token value changes

When a supported tool starts with auto-auth enabled, the tool requests a Vault
token using the configured method. If the request fails, the tool retries the
request with an exponential back off.

Once the request succeeds, the auth-auth renews unwrapped authentication tokens
automatically until Vault denies the renewal. If the authentication method wraps
tokens, auto-authentication cannot renew the token automatically.

Vault typically denies renewal if the token:

- the token was revoked.
- the token has exceeded the maximum number of uses.
- the token is otherwise invalid.

Every time authentication succeeds, auto-auth writes the token to any
appropriately configured sink.

## Advanced functionality

Sinks support some advanced features, including the ability for the written
values to be encrypted or
[response-wrapped](/vault/docs/concepts/response-wrapping).

Both mechanisms can be used concurrently; in this case, the value will be
response-wrapped, then encrypted.

### Response-Wrapping tokens

There are two ways that tokens can be response-wrapped:

1. By the auth method. This allows the end client to introspect the
   `creation_path` of the token, helping prevent Man-In-The-Middle (MITM)
   attacks. However, because auto-auth cannot then unwrap the token and rewrap
   it without modifying the `creation_path`, we are not able to renew the
   token; it is up to the end client to renew the token. Agent and Proxy both
   stay daemonized in this mode since some auth methods allow for reauthentication
   on certain events.

2. By any of the token sinks. Because more than one sink can be configured, the
   token must be wrapped after it is fetched, rather than wrapped by Vault as
   it's being returned. As a result, the `creation_path` will always be
   `sys/wrapping/wrap`, and validation of this field cannot be used as
   protection against MITM attacks. However, this mode allows auto-auth to keep
   the token renewed for the end client and automatically reauthenticate when
   it expires.

### Encrypting tokens

~> Support for encrypted tokens is experimental; if input/output formats
change, we will make every effort to provide backwards compatibility.

Tokens can be encrypted, using a Diffie-Hellman exchange to generate an
ephemeral key. In this mechanism, the client receiving the token writes a
generated public key to a file. The sink responsible for writing the token to
that client looks for this public key and uses it to compute a shared secret
key, which is then used to encrypt the token via AES-GCM. The nonce, encrypted
payload, and the sink's public key are then written to the output file, where
the client can compute the shared secret and decrypt the token value.

~> NOTE: Token encryption is not a protection against MITM attacks! The purpose
of this feature is for forward-secrecy and coverage against bare token values
being persisted. A MITM that can write to the sink's output and/or client
public-key input files could attack this exchange. Using TLS to protect the
transit of tokens is highly recommended.

To help mitigate MITM attacks, additional authenticated data (AAD) can be
provided to Agent and Proxy. This data is written as part of the AES-GCM tag and must
match on both Agent and Proxy and the client. This of course means that protecting
this AAD becomes important, but it provides another layer for an attacker to
have to overcome. For instance, if the attacker has access to the file system
where the token is being written, but not to read configuration or read
environment variables, this AAD can be generated and passed to Agent or Proxy and
the client in ways that would be difficult for the attacker to find.

When using AAD, it is always a good idea for this to be as fresh as possible;
generate a value and pass it to your client and Agent or Proxy on startup. Additionally,
Agent and Proxy a Trust On First Use model; after it finds a generated public key,
it will reuse that public key instead of looking for new values that have been
written.

If writing a client that uses this feature, it will likely be helpful to look
at the
[dhutil](https://github.com/hashicorp/vault/blob/main/helper/dhutil/dhutil.go)
library. This shows the expected format of the public key input and envelope
output formats.

## Configuration

The top level `auto_auth` block has two configuration entries:

- `method` `(object: required)` - Configuration for the method

- `sinks` `(array of objects: optional)` - Configuration for the sinks

- `enable_reauth_on_new_credentials` `(bool: false)` - If enabled, Auto-auth will
  handle new credential events from supported auth methods (AliCloud/AWS/Cert/JWT/LDAP/OCI)
  and re-authenticate with the new credential.

### Configuration (Method)

~> Auto-auth does not support using tokens with a limited number of uses. Auto-auth
does not track the number of uses remaining, and may allow the token to
expire before attempting to renew it. For example, if using AppRole auto-auth,
you must use 0 (meaning unlimited) as the value for
[`token_num_uses`](/vault/api-docs/auth/approle#token_num_uses).

These are common configuration values that live within the `method` block:

- `type` `(string: required)` - The type of the method to use, e.g. `aws`,
  `gcp`, `azure`, etc. _Note_: when using HCL this can be used as the key for
  the block, e.g. `method "aws" {...}`.

- `mount_path` `(string: optional)` - The mount path of the method. If not
  specified, defaults to a value of `auth/<method type>`.

- `namespace` `(string: optional)` - Namespace in which the mount lives.
  The order of precedence is: this setting lowest, followed by the
  environment variable `VAULT_NAMESPACE`, and then the highest precedence
  command-line option `-namespace`.
  If none of these are specified, defaults to the root namespace.
  Note that because sink response wrapping and templating are also based
  on the client created by auto-auth, they use the same namespace.
  If specified alongside the `namespace` option in the Vault Stanza of
  [Vault Agent](/vault/docs/agent-and-proxy/agent#vault-stanza) or
  [Vault Proxy](/vault/docs/agent-and-proxy/proxy#vault-stanza), that
  configuration will take precedence on everything except auto-auth.

- `wrap_ttl` `(string or integer: optional)` - If specified, the written token
  will be response-wrapped by auto-auth. This is more secure than wrapping by
  sinks, but does not allow the auto-auth to keep the token renewed or
  automatically reauthenticate when it expires. Rather than a simple string,
  the written value will be a JSON-encoded
  [SecretWrapInfo](https://godoc.org/github.com/hashicorp/vault/api#SecretWrapInfo)
  structure. Uses [duration format strings](/vault/docs/concepts/duration-format).

- `min_backoff` `(string or integer: "1s")` - The minimum backoff time auto-auth
  will delay before retrying after a failed auth attempt. The backoff will start
  at the configured value and double (with some randomness) after successive
  failures, capped by `max_backoff.` If Agent templating is being used, this
  value is also used as the min backoff time for the templating server.
  Uses [duration format strings](/vault/docs/concepts/duration-format).

- `max_backoff` `(string or integer: "5m")` - The maximum time Agent will delay
  before retrying after a failed auth attempt. The backoff will start at
  `min_backoff` and double (with some randomness) after successive failures,
  capped by `max_backoff.` If Agent templating is being used, this value is also
  used as the max backoff time for the templating server. `max_backoff` is the
  duration between retries, and **not** the duration that retries will be
  performed before giving up. Uses [duration format strings](/vault/docs/concepts/duration-format).

- `exit_on_err` `(bool: false)` - When set to true, Vault Agent and Vault Proxy
  will exit if any errors occur during authentication. This configurable only affects login
  attempts for new tokens (either initial or expired tokens) and will not exit for errors on
  valid token renewals.

- `config` `(object: required)` - Configuration of the method itself. See the
  sidebar for information about each method.

### Configuration (Sinks)

These configuration values are common to all Sinks:

- `type` `(string: required)` - The type of the method to use, e.g. `file`.
  _Note_: when using HCL this can be used as the key for the block, e.g. `sink "file" {...}`.

- `wrap_ttl` `(string or integer: optional)` - If specified, the written token
  will be response-wrapped by the sink. This is less secure than wrapping by
  the method, but allows auto-auth to keep the token renewed and automatically
  reauthenticate when it expires. Rather than a simple string, the written
  value will be a JSON-encoded
  [SecretWrapInfo](https://godoc.org/github.com/hashicorp/vault/api#SecretWrapInfo)
  structure. Uses [duration format strings](/vault/docs/concepts/duration-format).

- `dh_type` `(string: optional)` - If specified, the type of Diffie-Hellman exchange to
  perform, meaning, which ciphers and/or curves. Currently only `curve25519` is
  supported.

- `dh_path` `(string: required if dh_type is set)` - The path from which the
  auto-auth should read the client's initial parameters (e.g. curve25519 public
  key).

- `derive_key` `(bool: false)` - If specified, the final encryption key is
  calculated by using HKDF-SHA256 to derive a key from the calculated shared
  secret and the two public keys for enhanced security. This is recommended
  if backward compatibility isn't a concern.

- `aad` `(string: optional)` - If specified, additional authenticated data to
  use with the AES-GCM encryption of the token. Can be any string, including
  serialized data.

- `aad_env_var` `(string: optional)` - If specified, AAD will be read from the
  given environment variable rather than a value in the configuration file.

- `config` `(object: required)` - Configuration of the sink itself. See the
  sidebar for information about each sink.

### Auto auth examples

Auto-auth configuration objects take two separate forms when specified in HCL
and JSON. The following examples are meant to clarify the differences between
the two formats.

#### Sinks (HCL format)

The HCL format may define any number of sink objects with an optional wrapping
`sinks {...}` object.

~> Note: The [corresponding JSON format](#sinks-json-format) _must_ specify a
`"sinks" : [...]` array to encapsulate all `sink` JSON objects.

```hcl
// Other Vault Agent or Vault Proxy configuration blocks
// ...

auto_auth {
  method {
    type = "approle"

    config = {
      role_id_file_path = "/etc/vault/roleid"
      secret_id_file_path = "/etc/vault/secretid"
    }
  }

  sinks {
    sink {
      type = "file"

      config = {
        path = "/tmp/file-foo"
      }
    }
  }
}
```

The following valid HCL omits the wrapping `sinks` object while specifying
multiple sinks.

```hcl
// Other Vault Agent or Vault Proxy configuration blocks
// ...

auto_auth {
  method {
    type = "approle"

    config = {
      role_id_file_path = "/etc/vault/roleid"
      secret_id_file_path = "/etc/vault/secretid"
    }
  }

  sink {
    type = "file"

    config = {
      path = "/tmp/file-foo"
    }
  }

  sink {
    type = "file"

    config = {
      path = "/tmp/file-bar"
    }
  }
}
```

#### Sinks (JSON format)

The following JSON configuration illustrates the need for a `sinks: [...]` array
wrapping any number of `sink` objects.

```hcl
{
  "auto_auth" : {
    "method" : [
      {
        type = "approle"

        config = {
          role_id_file_path = "/etc/vault/roleid"
          secret_id_file_path = "/etc/vault/secretid"
        }
      }
    ],
    "sinks" : [
      {
        "sink" : {
          type = "file"

          config = {
            path = "/tmp/file-foo"
          }
        }
      }
    ]
  }
}
```

Multiple sinks are defined by appending more `sink` objects within the `sinks`
array:

```hcl
{
  "auto_auth" : {
    "method" : [
      {
        type = "approle"

        config = {
          role_id_file_path = "/etc/vault/roleid"
          secret_id_file_path = "/etc/vault/secretid"
        }
      }
    ],
    "sinks" : [
      {
        "sink" : {
          type = "file"

          config = {
            path = "/tmp/file-foo"
          }
        }
      },
      {
        "sink" : {
          type = "file"

          config = {
            path = "/tmp/file-bar"
          }
        }
      }
    ]
  }
}
```

layout  docs page title  What is Auto authentication  description       Use auto authentication with Vault Agent or Vault Proxy to simplify client   authentication to Vault in a variety of environments         What is Auto authentication   Auto authentication simplifies client authentication in a wide variety of environments  The following Vault tools come with auto authentication built in     Vault Agent   Vault Proxy     Methods and sinks  Auto auth consists of two parts     a   method     the desired authentication method for the current environment   a   sink     the location where tools save tokens when the token value changes  When a supported tool starts with auto auth enabled  the tool requests a Vault token using the configured method  If the request fails  the tool retries the request with an exponential back off   Once the request succeeds  the auth auth renews unwrapped authentication tokens automatically until Vault denies the renewal  If the authentication method wraps tokens  auto authentication cannot renew the token automatically   Vault typically denies renewal if the token     the token was revoked    the token has exceeded the maximum number of uses    the token is otherwise invalid   Every time authentication succeeds  auto auth writes the token to any appropriately configured sink      Advanced functionality  Sinks support some advanced features  including the ability for the written values to be encrypted or  response wrapped   vault docs concepts response wrapping    Both mechanisms can be used concurrently  in this case  the value will be response wrapped  then encrypted       Response Wrapping tokens  There are two ways that tokens can be response wrapped   1  By the auth method  This allows the end client to introspect the     creation path  of the token  helping prevent Man In The Middle  MITM     attacks  However  because auto auth cannot then unwrap the token and rewrap    it without modifying the  creation path   we are not able to renew the    token  it is up to the end client to renew the token  Agent and Proxy both    stay daemonized in this mode since some auth methods allow for reauthentication    on certain events   2  By any of the token sinks  Because more than one sink can be configured  the    token must be wrapped after it is fetched  rather than wrapped by Vault as    it s being returned  As a result  the  creation path  will always be     sys wrapping wrap   and validation of this field cannot be used as    protection against MITM attacks  However  this mode allows auto auth to keep    the token renewed for the end client and automatically reauthenticate when    it expires       Encrypting tokens     Support for encrypted tokens is experimental  if input output formats change  we will make every effort to provide backwards compatibility   Tokens can be encrypted  using a Diffie Hellman exchange to generate an ephemeral key  In this mechanism  the client receiving the token writes a generated public key to a file  The sink responsible for writing the token to that client looks for this public key and uses it to compute a shared secret key  which is then used to encrypt the token via AES GCM  The nonce  encrypted payload  and the sink s public key are then written to the output file  where the client can compute the shared secret and decrypt the token value      NOTE  Token encryption is not a protection against MITM attacks  The purpose of this feature is for forward secrecy and coverage against bare token values being persisted  A MITM that can write to the sink s output and or client public key input files could attack this exchange  Using TLS to protect the transit of tokens is highly recommended   To help mitigate MITM attacks  additional authenticated data  AAD  can be provided to Agent and Proxy  This data is written as part of the AES GCM tag and must match on both Agent and Proxy and the client  This of course means that protecting this AAD becomes important  but it provides another layer for an attacker to have to overcome  For instance  if the attacker has access to the file system where the token is being written  but not to read configuration or read environment variables  this AAD can be generated and passed to Agent or Proxy and the client in ways that would be difficult for the attacker to find   When using AAD  it is always a good idea for this to be as fresh as possible  generate a value and pass it to your client and Agent or Proxy on startup  Additionally  Agent and Proxy a Trust On First Use model  after it finds a generated public key  it will reuse that public key instead of looking for new values that have been written   If writing a client that uses this feature  it will likely be helpful to look at the  dhutil  https   github com hashicorp vault blob main helper dhutil dhutil go  library  This shows the expected format of the public key input and envelope output formats      Configuration  The top level  auto auth  block has two configuration entries      method    object  required     Configuration for the method     sinks    array of objects  optional     Configuration for the sinks     enable reauth on new credentials    bool  false     If enabled  Auto auth will   handle new credential events from supported auth methods  AliCloud AWS Cert JWT LDAP OCI    and re authenticate with the new credential       Configuration  Method      Auto auth does not support using tokens with a limited number of uses  Auto auth does not track the number of uses remaining  and may allow the token to expire before attempting to renew it  For example  if using AppRole auto auth  you must use 0  meaning unlimited  as the value for   token num uses    vault api docs auth approle token num uses    These are common configuration values that live within the  method  block      type    string  required     The type of the method to use  e g   aws      gcp    azure   etc   Note   when using HCL this can be used as the key for   the block  e g   method  aws              mount path    string  optional     The mount path of the method  If not   specified  defaults to a value of  auth  method type        namespace    string  optional     Namespace in which the mount lives    The order of precedence is  this setting lowest  followed by the   environment variable  VAULT NAMESPACE   and then the highest precedence   command line option   namespace     If none of these are specified  defaults to the root namespace    Note that because sink response wrapping and templating are also based   on the client created by auto auth  they use the same namespace    If specified alongside the  namespace  option in the Vault Stanza of    Vault Agent   vault docs agent and proxy agent vault stanza  or    Vault Proxy   vault docs agent and proxy proxy vault stanza   that   configuration will take precedence on everything except auto auth      wrap ttl    string or integer  optional     If specified  the written token   will be response wrapped by auto auth  This is more secure than wrapping by   sinks  but does not allow the auto auth to keep the token renewed or   automatically reauthenticate when it expires  Rather than a simple string    the written value will be a JSON encoded    SecretWrapInfo  https   godoc org github com hashicorp vault api SecretWrapInfo    structure  Uses  duration format strings   vault docs concepts duration format       min backoff    string or integer   1s      The minimum backoff time auto auth   will delay before retrying after a failed auth attempt  The backoff will start   at the configured value and double  with some randomness  after successive   failures  capped by  max backoff   If Agent templating is being used  this   value is also used as the min backoff time for the templating server    Uses  duration format strings   vault docs concepts duration format       max backoff    string or integer   5m      The maximum time Agent will delay   before retrying after a failed auth attempt  The backoff will start at    min backoff  and double  with some randomness  after successive failures    capped by  max backoff   If Agent templating is being used  this value is also   used as the max backoff time for the templating server   max backoff  is the   duration between retries  and   not   the duration that retries will be   performed before giving up  Uses  duration format strings   vault docs concepts duration format       exit on err    bool  false     When set to true  Vault Agent and Vault Proxy   will exit if any errors occur during authentication  This configurable only affects login   attempts for new tokens  either initial or expired tokens  and will not exit for errors on   valid token renewals      config    object  required     Configuration of the method itself  See the   sidebar for information about each method       Configuration  Sinks   These configuration values are common to all Sinks      type    string  required     The type of the method to use  e g   file      Note   when using HCL this can be used as the key for the block  e g   sink  file              wrap ttl    string or integer  optional     If specified  the written token   will be response wrapped by the sink  This is less secure than wrapping by   the method  but allows auto auth to keep the token renewed and automatically   reauthenticate when it expires  Rather than a simple string  the written   value will be a JSON encoded    SecretWrapInfo  https   godoc org github com hashicorp vault api SecretWrapInfo    structure  Uses  duration format strings   vault docs concepts duration format       dh type    string  optional     If specified  the type of Diffie Hellman exchange to   perform  meaning  which ciphers and or curves  Currently only  curve25519  is   supported      dh path    string  required if dh type is set     The path from which the   auto auth should read the client s initial parameters  e g  curve25519 public   key       derive key    bool  false     If specified  the final encryption key is   calculated by using HKDF SHA256 to derive a key from the calculated shared   secret and the two public keys for enhanced security  This is recommended   if backward compatibility isn t a concern      aad    string  optional     If specified  additional authenticated data to   use with the AES GCM encryption of the token  Can be any string  including   serialized data      aad env var    string  optional     If specified  AAD will be read from the   given environment variable rather than a value in the configuration file      config    object  required     Configuration of the sink itself  See the   sidebar for information about each sink       Auto auth examples  Auto auth configuration objects take two separate forms when specified in HCL and JSON  The following examples are meant to clarify the differences between the two formats        Sinks  HCL format   The HCL format may define any number of sink objects with an optional wrapping  sinks        object      Note  The  corresponding JSON format   sinks json format   must  specify a   sinks           array to encapsulate all  sink  JSON objects      hcl    Other Vault Agent or Vault Proxy configuration blocks         auto auth     method       type    approle       config           role id file path     etc vault roleid        secret id file path     etc vault secretid               sinks       sink         type    file         config             path     tmp file foo                           The following valid HCL omits the wrapping  sinks  object while specifying multiple sinks      hcl    Other Vault Agent or Vault Proxy configuration blocks         auto auth     method       type    approle       config           role id file path     etc vault roleid        secret id file path     etc vault secretid               sink       type    file       config           path     tmp file foo               sink       type    file       config           path     tmp file bar                        Sinks  JSON format   The following JSON configuration illustrates the need for a  sinks         array wrapping any number of  sink  objects      hcl      auto auth           method                      type    approle           config               role id file path     etc vault roleid            secret id file path     etc vault secretid                                sinks                       sink                type    file             config                 path     tmp file foo                                                 Multiple sinks are defined by appending more  sink  objects within the  sinks  array      hcl      auto auth           method                      type    approle           config               role id file path     etc vault roleid            secret id file path     etc vault secretid                                sinks                       sink                type    file             config                 path     tmp file foo                                                  sink                type    file             config                 path     tmp file bar


vault Vault Proxy Auto auth method application roles AppRole layout docs page title Auto auth with AppRole Use application roles for auto authentication with Vault Agent or

Answer:
---
layout: docs
page_title: Auto-auth with AppRole
description: >-
  Use application roles for auto-authentication with Vault Agent or
  Vault Proxy.
---

# Auto-auth method: application roles (AppRole)

The `approle` method reads in a role ID and a secret ID from files and sends
the values to the [AppRole Auth
method](/vault/docs/auth/approle).

The method caches values and it is safe to delete the role ID/secret ID files
after they have been read. In fact, by default, after reading the secret ID,
the agent will delete the file. New files or values written at the expected
locations will be used on next authentication and the new values will be
cached.

## Configuration

- `role_id_file_path` `(string: required)` - The path to the file with role ID

- `secret_id_file_path` `(string: optional)` - The path to the file with secret
  ID.
  If not set, only the `role-id` will be used.
  In that case, the AppRole should have `bind_secret_id` set to `false` otherwise
  Vault Agent wouldn't be able to login.

- `remove_secret_id_file_after_reading` `(bool: optional, defaults to true)` -
  This can be set to `false` to disable the default behavior of removing the
  secret ID file after it's been read.

- `secret_id_response_wrapping_path` `(string: optional)` - If set, the value
  at `secret_id_file_path` will be expected to be a [Response-Wrapping
  Token](/vault/docs/concepts/response-wrapping)
  containing the output of the secret ID retrieval endpoint for the role (e.g.
  `auth/approle/role/webservers/secret-id`) and the creation path for the
  response-wrapping token must match the value set here.

## Example configuration

An example configuration, using approle to enable [auto-auth](/vault/docs/agent-and-proxy/autoauth)
and creating both a plaintext token sink and a [response-wrapped token sink file](/vault/docs/agent-and-proxy/autoauth#wrap_ttl), follows:

```hcl
pid_file = "./pidfile"

vault {
  address = "https://127.0.0.1:8200"
}

auto_auth {
  method {
    type      = "approle"

    config = {
      role_id_file_path = "roleid"
      secret_id_file_path = "secretid"
      remove_secret_id_file_after_reading = false
    }
  }

  sink {
    type = "file"
    wrap_ttl = "30m"
    config = {
      path = "sink_file_wrapped_1.txt"
    }
  }

  sink {
    type = "file"
    config = {
      path = "sink_file_unwrapped_2.txt"
    }
  }
}

api_proxy {
  use_auto_auth_token = true
}

listener "tcp" {
  address = "127.0.0.1:8100"
  tls_disable = true
}

template {
  source      = "/etc/vault/server.key.ctmpl"
  destination = "/etc/vault/server.key"
}

template {
  source      = "/etc/vault/server.crt.ctmpl"
  destination = "/etc/vault/server.crt"
}
```

layout  docs page title  Auto auth with AppRole description       Use application roles for auto authentication with Vault Agent or   Vault Proxy         Auto auth method  application roles  AppRole   The  approle  method reads in a role ID and a secret ID from files and sends the values to the  AppRole Auth method   vault docs auth approle    The method caches values and it is safe to delete the role ID secret ID files after they have been read  In fact  by default  after reading the secret ID  the agent will delete the file  New files or values written at the expected locations will be used on next authentication and the new values will be cached      Configuration     role id file path    string  required     The path to the file with role ID     secret id file path    string  optional     The path to the file with secret   ID    If not set  only the  role id  will be used    In that case  the AppRole should have  bind secret id  set to  false  otherwise   Vault Agent wouldn t be able to login      remove secret id file after reading    bool  optional  defaults to true       This can be set to  false  to disable the default behavior of removing the   secret ID file after it s been read      secret id response wrapping path    string  optional     If set  the value   at  secret id file path  will be expected to be a  Response Wrapping   Token   vault docs concepts response wrapping    containing the output of the secret ID retrieval endpoint for the role  e g     auth approle role webservers secret id   and the creation path for the   response wrapping token must match the value set here      Example configuration  An example configuration  using approle to enable  auto auth   vault docs agent and proxy autoauth  and creating both a plaintext token sink and a  response wrapped token sink file   vault docs agent and proxy autoauth wrap ttl   follows      hcl pid file      pidfile   vault     address    https   127 0 0 1 8200     auto auth     method       type         approle       config           role id file path    roleid        secret id file path    secretid        remove secret id file after reading   false              sink       type    file      wrap ttl    30m      config           path    sink file wrapped 1 txt               sink       type    file      config           path    sink file unwrapped 2 txt                api proxy     use auto auth token   true    listener  tcp      address    127 0 0 1 8100    tls disable   true    template     source          etc vault server key ctmpl    destination     etc vault server key     template     source          etc vault server crt ctmpl    destination     etc vault server crt


vault page title What is Vault Proxy Vault Proxy is a server side daemon with caching and auto authentication that acts as load balancer and API proxy for Vault layout docs What is Vault Proxy

Answer:
---
layout: docs
page_title: What is Vault Proxy?
description: >-
  Vault Proxy is a server-side daemon with caching and auto-authentication that
  acts as load-balancer and API proxy for Vault.
---

# What is Vault Proxy?

Vault Proxy aims to remove the initial hurdle to adopt Vault by providing a
more scalable and simpler way for applications to integrate with Vault.
Vault Proxy acts as an [API Proxy][apiproxy] for Vault, and can optionally allow
or force interacting clients to use its [automatically authenticated token][autoauth].

Vault Proxy is a client daemon that provides the following features:

- [Auto-Auth][autoauth] - Automatically authenticate to Vault and manage the
token renewal process for locally-retrieved dynamic secrets.
- [API Proxy][apiproxy] - Acts as a proxy for Vault's API,
optionally using (or forcing the use of) the Auto-Auth token.
- [Caching][caching] - Allows client-side caching of responses containing newly
created tokens and responses containing leased secrets generated off of these
newly created tokens. The agent also manages the renewals of the cached tokens and leases.

## Auto-Auth

Vault Proxy allows easy authentication to Vault in a wide variety of
environments. Please see the [Auto-Auth docs][autoauth]
for information.

Auto-Auth functionality takes place within an `auto_auth` configuration stanza.

## API proxy

Vault Proxy's primary purpose is to act as an API proxy for Vault, allowing you to talk to Vault's
API via a listener. It can be configured to optionally allow or force the automatic use of
the Auto-Auth token for these requests. Please see the [API Proxy docs][apiproxy]
for more information.

API Proxy functionality takes place within a defined `listener`, and its behaviour can be configured with an
[`api_proxy` stanza](/vault/docs/agent-and-proxy/proxy/apiproxy#configuration-api_proxy).

## Caching

Vault Proxy allows client-side caching of responses containing newly created tokens
and responses containing leased secrets generated off of these newly created tokens.
Please see the [Caching docs][caching] for information.

## API

### Quit

This endpoint triggers shutdown of the proxy. By default, it is disabled, and can
be enabled per listener using the [`proxy_api`][proxy-api] stanza. It is recommended
to only enable this on trusted interfaces, as it does not require any authorization to use.

| Method | Path             |
| :----- | :--------------- |
| `POST` | `/proxy/v1/quit` |

### Cache

See the [caching](/vault/docs/agent-and-proxy/proxy/caching#api) page for details on the cache API.

## Configuration

### Command options

- `-log-level` ((#\_log_level)) `(string: "info")` - Log verbosity level. Supported values (in
order of descending detail) are `trace`, `debug`, `info`, `warn`, and `error`. This can
also be specified via the `VAULT_LOG_LEVEL` environment variable.

- `-log-format` ((#\_log_format)) `(string: "standard")` - Log format. Supported values
are `standard` and `json`. This can also be specified via the
`VAULT_LOG_FORMAT` environment variable.

- `-log-file` ((#\_log_file)) - the absolute path where Vault Proxy should save
  log messages. Paths that end with a path separator use the default file name,
  `proxy.log`. Paths that do not end with a file extension use the default
  `.log` extension. If the log file rotates, Vault Proxy appends the current
  timestamp to the file name at the time of rotation. For example:

  `log-file` | Full log file | Rotated log file
  ---------- | ------------- | ----------------
  `/var/log` | `/var/log/proxy.log` | `/var/log/proxy-{timestamp}.log`
  `/var/log/my-diary` | `/var/log/my-diary.log` | `/var/log/my-diary-{timestamp}.log`
  `/var/log/my-diary.txt` | `/var/log/my-diary.txt` | `/var/log/my-diary-{timestamp}.txt`

- `-log-rotate-bytes` ((#\_log_rotate_bytes)) - to specify the number of
bytes that should be written to a log before it needs to be rotated. Unless specified,
there is no limit to the number of bytes that can be written to a log file.

- `-log-rotate-duration` ((#\_log_rotate_duration)) - to specify the maximum
duration a log should be written to before it needs to be rotated. Must be a duration
value such as 30s. Defaults to 24h.

- `-log-rotate-max-files` ((#\_log_rotate_max_files)) - to specify the maximum
number of older log file archives to keep. Defaults to `0` (no files are ever deleted).
Set to `-1` to discard old log files when a new one is created.

### Configuration file options

These are the currently-available general configuration options:

- `vault` ([vault][vault]: <optional\>) - Specifies the remote Vault server the Proxy connects to.

- `auto_auth` ([auto_auth][autoauth]: <optional\>) - Specifies the method and other options used for Auto-Auth functionality.

- `api_proxy` ([api_proxy][apiproxy]: <optional\>) - Specifies options used for API Proxy functionality.

- `cache` ([cache][caching]: <optional\>) - Specifies options used for Caching functionality.

- `listener` ([listener][listener]: <optional\>) - Specifies the addresses and ports on which the Proxy will respond to requests.

~> **Note:** On `SIGHUP` (`kill -SIGHUP $(pidof vault)`), Vault Proxy will attempt to reload listener TLS configuration.
This method can be used to refresh certificates used by Vault Proxy without having to restart its process.

- `pid_file` `(string: "")` - Path to the file in which the Proxy's Process ID
(PID) should be stored

- `exit_after_auth` `(bool: false)` - If set to `true`, the proxy will exit
with code `0` after a single successful auth, where success means that a
token was retrieved and all sinks successfully wrote it

- `disable_idle_connections` `(string array: [])` - A list of strings that disables idle connections for various features in Vault Proxy.
Valid values include: `auto-auth`, and `proxying`. Can also be configured by setting the `VAULT_PROXY_DISABLE_IDLE_CONNECTIONS`
environment variable as a comma separated string. This environment variable will override any values found in a configuration file.

- `disable_keep_alives` `(string array: [])` - A list of strings that disables keep alives for various features in Vault Agent.
Valid values include: `auto-auth`, and `proxying`. Can also be configured by setting the `VAULT_PROXY_DISABLE_KEEP_ALIVES`
environment variable as a comma separated string. This environment variable will override any values found in a configuration file.

- `telemetry` ([telemetry][telemetry]: <optional\>) – Specifies the telemetry
reporting system. See the [telemetry Stanza](/vault/docs/agent-and-proxy/proxy#telemetry-stanza) section below
for a list of metrics specific to Proxy.

- `log_level` - Equivalent to the [`-log-level` command-line flag](#_log_level).

~> **Note:** On `SIGHUP` (`kill -SIGHUP $(pidof vault)`), Vault Proxy will update the log level to the value
specified by configuration file (including overriding values set using CLI or environment variable parameters).

- `log_format` - Equivalent to the [`-log-format` command-line flag](#_log_format).

- `log_file` - Equivalent to the [`-log-file` command-line flag](#_log_file).

- `log_rotate_duration` - Equivalent to the [`-log-rotate-duration` command-line flag](#_log_rotate_duration).

- `log_rotate_bytes` - Equivalent to the [`-log-rotate-bytes` command-line flag](#_log_rotate_bytes).

- `log_rotate_max_files` - Equivalent to the [`-log-rotate-max-files` command-line flag](#_log_rotate_max_files).

### vault stanza

There can at most be one top level `vault` block, and it has the following
configuration entries:

- `address` `(string: <optional>)` - The address of the Vault server to
connect to. This should be a Fully Qualified Domain Name (FQDN) or IP
such as `https://vault-fqdn:8200` or `https://172.16.9.8:8200`.
This value can be overridden by setting the `VAULT_ADDR` environment variable.

- `ca_cert` `(string: <optional>)` - Path on the local disk to a single PEM-encoded
CA certificate to verify the Vault server's SSL certificate. This value can
be overridden by setting the `VAULT_CACERT` environment variable.

- `ca_path` `(string: <optional>)` - Path on the local disk to a directory of
PEM-encoded CA certificates to verify the Vault server's SSL certificate.
This value can be overridden by setting the `VAULT_CAPATH` environment
variable.

- `client_cert` `(string: <optional>)` - Path on the local disk to a single
PEM-encoded CA certificate to use for TLS authentication to the Vault server.
This value can be overridden by setting the `VAULT_CLIENT_CERT` environment
variable.

- `client_key` `(string: <optional>)` - Path on the local disk to a single
PEM-encoded private key matching the client certificate from `client_cert`.
This value can be overridden by setting the `VAULT_CLIENT_KEY` environment
variable.

- `tls_skip_verify` `(string: <optional>)` - Disable verification of TLS
certificates. Using this option is highly discouraged as it decreases the
security of data transmissions to and from the Vault server. This value can
be overridden by setting the `VAULT_SKIP_VERIFY` environment variable.

- `tls_server_name` `(string: <optional>)` - Name to use as the SNI host when
connecting via TLS. This value can be overridden by setting the
`VAULT_TLS_SERVER_NAME` environment variable.

- `namespace` `(string: <optional>)` - Namespace to use for all of Vault Proxy's
requests to Vault. This can also be specified by command line or environment variable.
The order of precedence is: this setting lowest, followed by the environment variable
`VAULT_NAMESPACE`, and then the highest precedence command-line option `-namespace`.
If none of these are specified, defaults to the root namespace.

#### retry stanza

The `vault` stanza may contain a `retry` stanza that controls how failing Vault
requests are handled. Auto-auth, however, has its own notion of retrying and is not
affected by this section.

Here are the options for the `retry` stanza:

- `num_retries` `(int: 12)` - Specify how many times a failing request will
be retried. A value of `0` translates to the default, i.e. 12 retries.
A value of `-1` disables retries. The environment variable `VAULT_MAX_RETRIES`
overrides this setting.

Requests originating
from the proxy cache will only be retried if they resulted in specific HTTP
result codes: any 50x code except 501 ("not implemented"), as well as 412
("precondition failed"); 412 is used in Vault Enterprise 1.7+ to indicate a
stale read due to eventual consistency. Requests coming from the template
subsystem are retried regardless of the failure.

### listener stanza

Vault Proxy supports one or more [listener][listener_main] stanzas. Listeners
can be configured with or without [caching][caching], but will use the cache if it
has been configured, and will enable the [API proxy][apiproxy]. In addition to the standard
listener configuration, a Proxy's listener configuration also supports the following:

- `require_request_header` `(bool: false)` - Require that all incoming HTTP
requests on this listener must have an `X-Vault-Request: true` header entry.
Using this option offers an additional layer of protection from Server Side
Request Forgery attacks. Requests on the listener that do not have the proper
`X-Vault-Request` header will fail, with a HTTP response status code of `412: Precondition Failed`.

- `role` `(string: default)` - `role` determines which APIs the listener serves.
It can be configured to `metrics_only` to serve only metrics, or the default role, `default`,
which serves everything (including metrics). The `require_request_header` does not apply
to `metrics_only` listeners.

- `proxy_api` ([proxy_api][proxy-api]: <optional\>) - Manages optional Proxy API endpoints.

#### proxy_api stanza

- `enable_quit` `(bool: false)` - If set to `true`, the Proxy will enable the [quit](/vault/docs/agent-and-proxy/proxy#quit) API.

### telemetry stanza

Vault Proxy supports the [telemetry][telemetry] stanza and collects various
runtime metrics about its performance, the auto-auth and the cache status:

| Metric                           | Description                                          | Type    |
| -------------------------------- | ---------------------------------------------------- | ------- |
| `vault.proxy.auth.failure`       | Number of authentication failures                    | counter |
| `vault.proxy.auth.success`       | Number of authentication successes                   | counter |
| `vault.proxy.proxy.success`      | Number of requests successfully proxied              | counter |
| `vault.proxy.proxy.client_error` | Number of requests for which Vault returned an error | counter |
| `vault.proxy.proxy.error`        | Number of requests the proxy failed to proxy         | counter |
| `vault.proxy.cache.hit`          | Number of cache hits                                 | counter |
| `vault.proxy.cache.miss`         | Number of cache misses                               | counter |

## Start Vault proxy

To run Vault Proxy:

1. [Download](/vault/downloads) the Vault binary where the client application runs
(virtual machine, Kubernetes pod, etc.)

1. Create a Vault Proxy configuration file. (See the [Example
Configuration](#example-configuration) section for an example configuration.)

1. Start a Vault Proxy with the configuration file.

**Example:**

```shell-session
$ vault proxy -config=/etc/vault/proxy-config.hcl
   ```

To get help, run:

```shell-session
$ vault proxy -h
   ```

As with Vault, the `-config` flag can be used in three different ways:

- Use the flag once to name the path to a single specific configuration file.
- Use the flag multiple times to name multiple configuration files, which will be composed at runtime.
- Use the flag to name a directory of configuration files, the contents of which will be composed at runtime.

## Example configuration

An example configuration, with very contrived values, follows:

```hcl
pid_file = "./pidfile"

vault {
  address = "https://vault-fqdn:8200"
  retry {
    num_retries = 5
  }
}

auto_auth {
  method "aws" {
    mount_path = "auth/aws-subaccount"
    config = {
      type = "iam"
      role = "foobar"
    }
  }

  sink "file" {
    config = {
      path = "/tmp/file-foo"
    }
  }

  sink "file" {
    wrap_ttl = "5m"
    aad_env_var = "TEST_AAD_ENV"
    dh_type = "curve25519"
    dh_path = "/tmp/file-foo-dhpath2"
    config = {
      path = "/tmp/file-bar"
    }
  }
}

cache {
  // An empty cache stanza still enables caching
}

api_proxy {
  use_auto_auth_token = true
}

listener "unix" {
  address = "/path/to/socket"
  tls_disable = true

  agent_api {
    enable_quit = true
  }
}

listener "tcp" {
  address = "127.0.0.1:8100"
  tls_disable = true
}
```

[vault]: /vault/docs/agent-and-proxy/proxy#vault-stanza
[autoauth]: /vault/docs/agent-and-proxy/autoauth
[caching]: /vault/docs/agent-and-proxy/proxy/caching
[apiproxy]: /vault/docs/agent-and-proxy/proxy/apiproxy
[persistent-cache]: /vault/docs/agent-and-proxy/proxy/caching/persistent-caches
[proxy-api]: /vault/docs/agent-and-proxy/proxy/#proxy_api-stanza
[listener]: /vault/docs/agent-and-proxy/proxy#listener-stanza
[listener_main]: /vault/docs/configuration/listener/tcp
[telemetry]: /vault/docs/configuration/telemetry

layout  docs page title  What is Vault Proxy  description       Vault Proxy is a server side daemon with caching and auto authentication that   acts as load balancer and API proxy for Vault         What is Vault Proxy   Vault Proxy aims to remove the initial hurdle to adopt Vault by providing a more scalable and simpler way for applications to integrate with Vault  Vault Proxy acts as an  API Proxy  apiproxy  for Vault  and can optionally allow or force interacting clients to use its  automatically authenticated token  autoauth    Vault Proxy is a client daemon that provides the following features      Auto Auth  autoauth    Automatically authenticate to Vault and manage the token renewal process for locally retrieved dynamic secrets     API Proxy  apiproxy    Acts as a proxy for Vault s API  optionally using  or forcing the use of  the Auto Auth token     Caching  caching    Allows client side caching of responses containing newly created tokens and responses containing leased secrets generated off of these newly created tokens  The agent also manages the renewals of the cached tokens and leases      Auto Auth  Vault Proxy allows easy authentication to Vault in a wide variety of environments  Please see the  Auto Auth docs  autoauth  for information   Auto Auth functionality takes place within an  auto auth  configuration stanza      API proxy  Vault Proxy s primary purpose is to act as an API proxy for Vault  allowing you to talk to Vault s API via a listener  It can be configured to optionally allow or force the automatic use of the Auto Auth token for these requests  Please see the  API Proxy docs  apiproxy  for more information   API Proxy functionality takes place within a defined  listener   and its behaviour can be configured with an   api proxy  stanza   vault docs agent and proxy proxy apiproxy configuration api proxy       Caching  Vault Proxy allows client side caching of responses containing newly created tokens and responses containing leased secrets generated off of these newly created tokens  Please see the  Caching docs  caching  for information      API      Quit  This endpoint triggers shutdown of the proxy  By default  it is disabled  and can be enabled per listener using the   proxy api   proxy api  stanza  It is recommended to only enable this on trusted interfaces  as it does not require any authorization to use     Method   Path                                                POST      proxy v1 quit         Cache  See the  caching   vault docs agent and proxy proxy caching api  page for details on the cache API      Configuration      Command options      log level       log level     string   info      Log verbosity level  Supported values  in order of descending detail  are  trace    debug    info    warn   and  error   This can also be specified via the  VAULT LOG LEVEL  environment variable       log format       log format     string   standard      Log format  Supported values are  standard  and  json   This can also be specified via the  VAULT LOG FORMAT  environment variable       log file       log file     the absolute path where Vault Proxy should save   log messages  Paths that end with a path separator use the default file name     proxy log   Paths that do not end with a file extension use the default     log  extension  If the log file rotates  Vault Proxy appends the current   timestamp to the file name at the time of rotation  For example      log file    Full log file   Rotated log file                                                     var log      var log proxy log      var log proxy  timestamp  log      var log my diary      var log my diary log      var log my diary  timestamp  log      var log my diary txt      var log my diary txt      var log my diary  timestamp  txt       log rotate bytes       log rotate bytes     to specify the number of bytes that should be written to a log before it needs to be rotated  Unless specified  there is no limit to the number of bytes that can be written to a log file       log rotate duration       log rotate duration     to specify the maximum duration a log should be written to before it needs to be rotated  Must be a duration value such as 30s  Defaults to 24h       log rotate max files       log rotate max files     to specify the maximum number of older log file archives to keep  Defaults to  0   no files are ever deleted   Set to   1  to discard old log files when a new one is created       Configuration file options  These are the currently available general configuration options      vault   code   vault  vault    optional     code    Specifies the remote Vault server the Proxy connects to      auto auth   code   auto auth  autoauth    optional     code    Specifies the method and other options used for Auto Auth functionality      api proxy   code   api proxy  apiproxy    optional     code    Specifies options used for API Proxy functionality      cache   code   cache  caching    optional     code    Specifies options used for Caching functionality      listener   code   listener  listener    optional     code    Specifies the addresses and ports on which the Proxy will respond to requests        Note    On  SIGHUP    kill  SIGHUP   pidof vault     Vault Proxy will attempt to reload listener TLS configuration  This method can be used to refresh certificates used by Vault Proxy without having to restart its process      pid file    string         Path to the file in which the Proxy s Process ID  PID  should be stored     exit after auth    bool  false     If set to  true   the proxy will exit with code  0  after a single successful auth  where success means that a token was retrieved and all sinks successfully wrote it     disable idle connections    string array         A list of strings that disables idle connections for various features in Vault Proxy  Valid values include   auto auth   and  proxying   Can also be configured by setting the  VAULT PROXY DISABLE IDLE CONNECTIONS  environment variable as a comma separated string  This environment variable will override any values found in a configuration file      disable keep alives    string array         A list of strings that disables keep alives for various features in Vault Agent  Valid values include   auto auth   and  proxying   Can also be configured by setting the  VAULT PROXY DISABLE KEEP ALIVES  environment variable as a comma separated string  This environment variable will override any values found in a configuration file      telemetry   code   telemetry  telemetry    optional     code    Specifies the telemetry reporting system  See the  telemetry Stanza   vault docs agent and proxy proxy telemetry stanza  section below for a list of metrics specific to Proxy      log level    Equivalent to the    log level  command line flag    log level         Note    On  SIGHUP    kill  SIGHUP   pidof vault     Vault Proxy will update the log level to the value specified by configuration file  including overriding values set using CLI or environment variable parameters       log format    Equivalent to the    log format  command line flag    log format       log file    Equivalent to the    log file  command line flag    log file       log rotate duration    Equivalent to the    log rotate duration  command line flag    log rotate duration       log rotate bytes    Equivalent to the    log rotate bytes  command line flag    log rotate bytes       log rotate max files    Equivalent to the    log rotate max files  command line flag    log rotate max files        vault stanza  There can at most be one top level  vault  block  and it has the following configuration entries      address    string   optional      The address of the Vault server to connect to  This should be a Fully Qualified Domain Name  FQDN  or IP such as  https   vault fqdn 8200  or  https   172 16 9 8 8200   This value can be overridden by setting the  VAULT ADDR  environment variable      ca cert    string   optional      Path on the local disk to a single PEM encoded CA certificate to verify the Vault server s SSL certificate  This value can be overridden by setting the  VAULT CACERT  environment variable      ca path    string   optional      Path on the local disk to a directory of PEM encoded CA certificates to verify the Vault server s SSL certificate  This value can be overridden by setting the  VAULT CAPATH  environment variable      client cert    string   optional      Path on the local disk to a single PEM encoded CA certificate to use for TLS authentication to the Vault server  This value can be overridden by setting the  VAULT CLIENT CERT  environment variable      client key    string   optional      Path on the local disk to a single PEM encoded private key matching the client certificate from  client cert   This value can be overridden by setting the  VAULT CLIENT KEY  environment variable      tls skip verify    string   optional      Disable verification of TLS certificates  Using this option is highly discouraged as it decreases the security of data transmissions to and from the Vault server  This value can be overridden by setting the  VAULT SKIP VERIFY  environment variable      tls server name    string   optional      Name to use as the SNI host when connecting via TLS  This value can be overridden by setting the  VAULT TLS SERVER NAME  environment variable      namespace    string   optional      Namespace to use for all of Vault Proxy s requests to Vault  This can also be specified by command line or environment variable  The order of precedence is  this setting lowest  followed by the environment variable  VAULT NAMESPACE   and then the highest precedence command line option   namespace   If none of these are specified  defaults to the root namespace        retry stanza  The  vault  stanza may contain a  retry  stanza that controls how failing Vault requests are handled  Auto auth  however  has its own notion of retrying and is not affected by this section   Here are the options for the  retry  stanza      num retries    int  12     Specify how many times a failing request will be retried  A value of  0  translates to the default  i e  12 retries  A value of   1  disables retries  The environment variable  VAULT MAX RETRIES  overrides this setting   Requests originating from the proxy cache will only be retried if they resulted in specific HTTP result codes  any 50x code except 501   not implemented    as well as 412   precondition failed    412 is used in Vault Enterprise 1 7  to indicate a stale read due to eventual consistency  Requests coming from the template subsystem are retried regardless of the failure       listener stanza  Vault Proxy supports one or more  listener  listener main  stanzas  Listeners can be configured with or without  caching  caching   but will use the cache if it has been configured  and will enable the  API proxy  apiproxy   In addition to the standard listener configuration  a Proxy s listener configuration also supports the following      require request header    bool  false     Require that all incoming HTTP requests on this listener must have an  X Vault Request  true  header entry  Using this option offers an additional layer of protection from Server Side Request Forgery attacks  Requests on the listener that do not have the proper  X Vault Request  header will fail  with a HTTP response status code of  412  Precondition Failed       role    string  default      role  determines which APIs the listener serves  It can be configured to  metrics only  to serve only metrics  or the default role   default   which serves everything  including metrics   The  require request header  does not apply to  metrics only  listeners      proxy api   code   proxy api  proxy api    optional     code    Manages optional Proxy API endpoints        proxy api stanza     enable quit    bool  false     If set to  true   the Proxy will enable the  quit   vault docs agent and proxy proxy quit  API       telemetry stanza  Vault Proxy supports the  telemetry  telemetry  stanza and collects various runtime metrics about its performance  the auto auth and the cache status     Metric                             Description                                            Type                                                                                vault proxy auth failure          Number of authentication failures                      counter      vault proxy auth success          Number of authentication successes                     counter      vault proxy proxy success         Number of requests successfully proxied                counter      vault proxy proxy client error    Number of requests for which Vault returned an error   counter      vault proxy proxy error           Number of requests the proxy failed to proxy           counter      vault proxy cache hit             Number of cache hits                                   counter      vault proxy cache miss            Number of cache misses                                 counter       Start Vault proxy  To run Vault Proxy   1   Download   vault downloads  the Vault binary where the client application runs  virtual machine  Kubernetes pod  etc    1  Create a Vault Proxy configuration file   See the  Example Configuration   example configuration  section for an example configuration    1  Start a Vault Proxy with the configuration file     Example        shell session   vault proxy  config  etc vault proxy config hcl         To get help  run      shell session   vault proxy  h         As with Vault  the   config  flag can be used in three different ways     Use the flag once to name the path to a single specific configuration file    Use the flag multiple times to name multiple configuration files  which will be composed at runtime    Use the flag to name a directory of configuration files  the contents of which will be composed at runtime      Example configuration  An example configuration  with very contrived values  follows      hcl pid file      pidfile   vault     address    https   vault fqdn 8200    retry       num retries   5        auto auth     method  aws        mount path    auth aws subaccount      config           type    iam        role    foobar               sink  file        config           path     tmp file foo               sink  file        wrap ttl    5m      aad env var    TEST AAD ENV      dh type    curve25519      dh path     tmp file foo dhpath2      config           path     tmp file bar               cache        An empty cache stanza still enables caching    api proxy     use auto auth token   true    listener  unix      address     path to socket    tls disable   true    agent api       enable quit   true        listener  tcp      address    127 0 0 1 8100    tls disable   true         vault    vault docs agent and proxy proxy vault stanza  autoauth    vault docs agent and proxy autoauth  caching    vault docs agent and proxy proxy caching  apiproxy    vault docs agent and proxy proxy apiproxy  persistent cache    vault docs agent and proxy proxy caching persistent caches  proxy api    vault docs agent and proxy proxy  proxy api stanza  listener    vault docs agent and proxy proxy listener stanza  listener main    vault docs configuration listener tcp  telemetry    vault docs configuration telemetry


vault Vault Proxy s API Proxy functionality allows you to use Vault Proxy s API as a proxy Use Vault Proxy as an API proxy page title Use Vault Proxy as an API proxy layout docs Use auto authentication and configure Vault Proxy as a proxy for the Vault API

Answer:
---
layout: docs
page_title: Use Vault Proxy as an API proxy
description: >-
  Use auto-authentication and configure Vault Proxy as a proxy for the Vault API.
---

# 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](/vault/docs/agent-and-proxy/proxy#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](/vault/docs/agent-and-proxy/proxy#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](/vault/docs/agent-and-proxy/proxy/caching) 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](/vault/docs/agent-and-proxy/autoauth). 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](/vault/docs/agent-and-proxy/proxy/apiproxy#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](/vault/docs/agent-and-proxy/proxy#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](/vault/docs/enterprise/consistency#vault-proxy-and-consistency-headers)
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.

```hcl
# Other Vault Proxy configuration blocks
# ...

api_proxy {
  use_auto_auth_token = "force"
  enforce_consistency = "always"
}

listener "unix" {
    address = "/var/run/vault-proxy.sock
}
```

layout  docs page title  Use Vault Proxy as an API proxy description       Use auto authentication and configure Vault Proxy as a proxy for the Vault API         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   vault docs agent and proxy proxy 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   vault docs agent and proxy proxy 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   vault docs agent and proxy proxy caching  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   vault docs agent and proxy autoauth   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   vault docs agent and proxy proxy apiproxy 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   vault docs agent and proxy proxy 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   vault docs enterprise consistency vault proxy and consistency headers  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      hcl   Other Vault Proxy configuration blocks        api proxy     use auto auth token    force    enforce consistency    always     listener  unix        address     var run vault proxy sock


vault created tokens or leased secrets generated from a newly created token page title Vault Proxy caching overview Vault Proxy caching overview Use client side caching with Vault Proxy for responses with newly layout docs

Answer:
---
layout: docs
page_title: Vault Proxy caching overview
description: >-
  Use client-side caching with Vault Proxy for responses with newly
  created tokens or leased secrets generated from a newly created token.
---

# Vault Proxy caching overview

Vault Proxy caching allows client-side caching of responses containing newly
created tokens and responses containing leased secrets generated off of these
newly created tokens. The renewals of the cached tokens and leases are also
managed by the proxy. Additionally, with `cache_static_secrets` set to `true`,
Vault Proxy [can be configured to cache KVv1 and KVv2 secrets][static-secret-caching].

## Caching and renewals

Response caching and renewals for dynamic secrets are managed by Proxy only under these
specific scenarios.

1. Token creation requests are made through the proxy. This means that any
   login operations performed using various auth methods and invoking the token
   creation endpoints of the token auth method via the proxy will result in the
   response getting cached by the proxy. Responses containing new tokens will
   be cached by the proxy only if the parent token is already being managed by
   the proxy or if the new token is an orphan token.

2. Leased secret creation requests are made through the proxy using tokens that
   are already managed by the proxy. This means that any dynamic credentials
   that are issued using the tokens managed by the proxy, will be cached and
   its renewals are taken care of.

## Static secret caching

You can configure Vault Proxy to cache dynamic secrets and static (KVv1 and KVv2)
secrets. When you enable caching for static secrets. Proxy keeps a cached entry
of the secret but only provides the cached response to requests made with tokens
that can access the secret. As a result, multiple requests to Vault Proxy for
the same KV secret only require a single, initial request to be forwarded to Vault.

Static secret caching is disabled by default. To enable caching for static secrets you must
configure [auto-auth](/vault/docs/agent-and-proxy/autoauth) and ensure the
auto-auth token has permission to subscribe to KV
[event](/vault/docs/concepts/events) updates.

Once configured, Proxy uses the auto-auth token to subscribe to KV events, and
monitors the subscription feed to know when to update the secrets in its cache.

For more information on static secret caching, refer to the
[Vault Proxy static secret caching][static-secret-caching] overview.

## Persistent cache

Vault Proxy can restore secrets, such as, tokens, leases, and static secrets, from a persistent
cache file created by a previous Vault Proxy process.

Refer to the [Vault Proxy Persistent
Caching](/vault/docs/agent-and-proxy/proxy/caching/persistent-caches) page for more information on
this functionality.

## Cache evictions

The eviction of cache entries pertaining to dynamic secrets will occur when the proxy
can no longer renew them. This can happen when the secrets hit their maximum
TTL or if the renewals result in errors.

Vault Proxy does some best-effort cache evictions by observing specific request types
and response codes. For example, if a token revocation request is made via the
proxy and if the forwarded request to the Vault server succeeds, then proxy
evicts all the cache entries associated with the revoked token. Similarly, any
lease revocation operation will also be intercepted by the proxy and the
respective cache entries will be evicted.

Note that while proxy evicts the cache entries upon secret expirations and upon
intercepting revocation requests, it is still possible for the proxy to be
completely unaware of the revocations that happen through direct client
interactions with the Vault server. This could potentially lead to stale cache
entries. For managing the stale entries in the cache, an endpoint
`/proxy/v1/cache-clear`(see below) is made available to manually evict cache
entries based on some of the query criteria used for indexing the cache entries.

## Request uniqueness

In order to detect repeat requests and return cached responses, Proxy needs
to have a way to uniquely identify the requests. This computation as it stands
today takes a simplistic approach (may change in future) of serializing and
hashing the HTTP request along with all the headers and the request body. This
hash value is then used as an index into the cache to check if the response is
readily available. The consequence of this approach is that the hash value for
any request will differ if any data in the request is modified. This has the
side-effect of resulting in false negatives if say, the ordering of the request
parameters are modified. As long as the requests come in without any change,
caching behavior should be consistent. Identical requests with differently
ordered request values will result in duplicated cache entries. A heuristic
assumption that the clients will use consistent mechanisms to make requests,
thereby resulting in consistent hash values per request is the idea upon which
the caching functionality is built upon.

## Renewal management

The tokens and leases are renewed by the proxy using the secret renewer that is
made available via the Vault server's [Go
API](https://godoc.org/github.com/hashicorp/vault/api#Renewer). Proxy performs
all operations in memory and does not persist anything to storage. This means
that when the proxy is shut down, all the renewal operations are immediately
terminated and there is no way for the proxy to resume renewals after the fact.
Note that shutting down the proxy does not indicate revocations of the secrets,
instead it only means that renewal responsibility for all the valid unrevoked
secrets are no longer performed by the Vault proxy.

## API

### Cache clear

This endpoint clears the cache based on given criteria. To use this
API, some information on how the proxy caches values should be known
beforehand. Each response that is cached in the proxy will be indexed on some
factors depending on the type of request. Those factors can be the `token` that
is belonging to the cached response, the `token_accessor` of the token
belonging to the cached response, the `request_path` that resulted in the
cached response, the `lease` that is attached to the cached response, the
`namespace` to which the cached response belongs to, and a few more. This API
exposes some factors through which associated cache entries are fetched and
evicted. For listeners without caching enabled, this API will still be available,
but will do nothing (there is no cache to clear) and will return a `200` response.

| Method | Path                    | Produces               |
| :----- | :---------------------- | :--------------------- |
| `POST` | `/proxy/v1/cache-clear` | `200 application/json` |

#### Parameters

- `type` `(strings: required)` - The type of cache entries to evict. Valid
  values are `request_path`, `lease`, `token`, `token_accessor`, and `all`.
  If the `type` is set to `all`, the _entire cache_ is cleared.

- `value` `(string: required)` - An exact value or the prefix of the value for
  the `type` selected. This parameter is optional when the `type` is set
  to `all`.

- `namespace` `(string: optional)` - This is only applicable when the `type` is set to
  `request_path`. The namespace of which the cache entries to be evicted for
  the given request path.

### Sample payload

```json
{
  "type": "token",
  "value": "hvs.rlNjegSKykWcplOkwsjd8bP9"
}
```

### Sample request

```shell-session
$ curl \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:1234/proxy/v1/cache-clear
```

## Configuration (`cache`)

The presence of the top level `cache` block in any way (including an empty `cache` block)  will enable the cache.
Note that either `cache_static_secrets` must be `true` and/or `disable_caching_dynamic_secrets` must
be `false`, otherwise the cache does nothing. The top level `cache` block has the following configuration entries:

- `persist` `(object: optional)` - Configuration for the persistent cache.

- `cache_static_secrets` `(bool: false)` - Enables static secret caching when
`true`.

- `disable_caching_dynamic_secrets` `(bool: false)` - Disables dynamic secret caching when
`true`.

-> **Note:** When the `cache` block is defined, a [listener][proxy-listener] must also be defined
in the config, otherwise there is no way to utilize the cache.

[proxy-listener]: /vault/docs/agent-and-proxy/proxy#listener-stanza

### Configuration (Persist)

These are common configuration values that live within the `persist` block:

- `type` `(string: required)` - The type of the persistent cache to use,
  e.g. `kubernetes`. _Note_: when using HCL this can be used as the key for
  the block, e.g. `persist "kubernetes" {...}`. Currently, only `kubernetes`
  is supported.

- `path` `(string: required)` - The path on disk where the persistent cache file
  should be created or restored from.

- `keep_after_import` `(bool: optional)` - When set to true, a restored cache file
  is not deleted. Defaults to `false`.

- `exit_on_err` `(bool: optional)` - When set to true, if any errors occur during
  a persistent cache restore, Vault Proxy will exit with an error. Defaults to `true`.

- `service_account_token_file` `(string: optional)` - When `type` is set to `kubernetes`,
this configures the path on disk where the Kubernetes service account token can be found.
Defaults to `/var/run/secrets/kubernetes.io/serviceaccount/token`.

## Configuration (`listener`)

- `listener` `(array of objects: required)` - Configuration for the listeners.

There can be one or more `listener` blocks at the top level. Adding a listener enables
the [API Proxy](/vault/docs/agent-and-proxy/proxy/apiproxy) and enables the API proxy to use the cache, if configured.
These configuration values are common to both `tcp` and `unix` listener blocks. Blocks of type
`tcp` support the standard `tcp` [listener](/vault/docs/configuration/listener/tcp)
options. Additionally, the `role` string option is available as part of the top level
of the `listener` block, which can be configured to `metrics_only` to serve only metrics,
or the default role, `default`, which serves everything (including metrics).

- `type` `(string: required)` - The type of the listener to use. Valid values
  are `tcp` and `unix`.
  _Note_: when using HCL this can be used as the key for the block, e.g.
  `listener "tcp" {...}`.

- `address` `(string: required)` - The address for the listener to listen to.
  This can either be a URL path when using `tcp` or a file path when using
  `unix`. For example, `127.0.0.1:8200` or `/path/to/socket`. Defaults to
  `127.0.0.1:8200`.

- `tls_disable` `(bool: false)` - Specifies if TLS will be disabled.

- `tls_key_file` `(string: optional)` - Specifies the path to the private key
  for the certificate.

- `tls_cert_file` `(string: optional)` - Specifies the path to the certificate
  for TLS.

### Example configuration

Here is an example of a cache configuration with the optional `persist` block,
alongside a regular listener, and a listener that only serves metrics.

```hcl
# Other Vault Proxy configuration blocks
# ...

cache {
	persist = {
		type = "kubernetes"
		path = "/vault/proxy-cache/"
		keep_after_import = true
		exit_on_err = true
		service_account_token_file = "/tmp/serviceaccount/token"
	}
}

listener "tcp" {
    address = "127.0.0.1:8100"
    tls_disable = true
}

listener "tcp" {
    address = "127.0.0.1:3000"
    tls_disable = true
    role = "metrics_only"
}
```

[static-secret-caching]: /vault/docs/agent-and-proxy/proxy/caching/static-secret-caching

layout  docs page title  Vault Proxy caching overview description       Use client side caching with Vault Proxy for responses with newly   created tokens or leased secrets generated from a newly created token         Vault Proxy caching overview  Vault Proxy caching allows client side caching of responses containing newly created tokens and responses containing leased secrets generated off of these newly created tokens  The renewals of the cached tokens and leases are also managed by the proxy  Additionally  with  cache static secrets  set to  true   Vault Proxy  can be configured to cache KVv1 and KVv2 secrets  static secret caching       Caching and renewals  Response caching and renewals for dynamic secrets are managed by Proxy only under these specific scenarios   1  Token creation requests are made through the proxy  This means that any    login operations performed using various auth methods and invoking the token    creation endpoints of the token auth method via the proxy will result in the    response getting cached by the proxy  Responses containing new tokens will    be cached by the proxy only if the parent token is already being managed by    the proxy or if the new token is an orphan token   2  Leased secret creation requests are made through the proxy using tokens that    are already managed by the proxy  This means that any dynamic credentials    that are issued using the tokens managed by the proxy  will be cached and    its renewals are taken care of      Static secret caching  You can configure Vault Proxy to cache dynamic secrets and static  KVv1 and KVv2  secrets  When you enable caching for static secrets  Proxy keeps a cached entry of the secret but only provides the cached response to requests made with tokens that can access the secret  As a result  multiple requests to Vault Proxy for the same KV secret only require a single  initial request to be forwarded to Vault   Static secret caching is disabled by default  To enable caching for static secrets you must configure  auto auth   vault docs agent and proxy autoauth  and ensure the auto auth token has permission to subscribe to KV  event   vault docs concepts events  updates   Once configured  Proxy uses the auto auth token to subscribe to KV events  and monitors the subscription feed to know when to update the secrets in its cache   For more information on static secret caching  refer to the  Vault Proxy static secret caching  static secret caching  overview      Persistent cache  Vault Proxy can restore secrets  such as  tokens  leases  and static secrets  from a persistent cache file created by a previous Vault Proxy process   Refer to the  Vault Proxy Persistent Caching   vault docs agent and proxy proxy caching persistent caches  page for more information on this functionality      Cache evictions  The eviction of cache entries pertaining to dynamic secrets will occur when the proxy can no longer renew them  This can happen when the secrets hit their maximum TTL or if the renewals result in errors   Vault Proxy does some best effort cache evictions by observing specific request types and response codes  For example  if a token revocation request is made via the proxy and if the forwarded request to the Vault server succeeds  then proxy evicts all the cache entries associated with the revoked token  Similarly  any lease revocation operation will also be intercepted by the proxy and the respective cache entries will be evicted   Note that while proxy evicts the cache entries upon secret expirations and upon intercepting revocation requests  it is still possible for the proxy to be completely unaware of the revocations that happen through direct client interactions with the Vault server  This could potentially lead to stale cache entries  For managing the stale entries in the cache  an endpoint   proxy v1 cache clear  see below  is made available to manually evict cache entries based on some of the query criteria used for indexing the cache entries      Request uniqueness  In order to detect repeat requests and return cached responses  Proxy needs to have a way to uniquely identify the requests  This computation as it stands today takes a simplistic approach  may change in future  of serializing and hashing the HTTP request along with all the headers and the request body  This hash value is then used as an index into the cache to check if the response is readily available  The consequence of this approach is that the hash value for any request will differ if any data in the request is modified  This has the side effect of resulting in false negatives if say  the ordering of the request parameters are modified  As long as the requests come in without any change  caching behavior should be consistent  Identical requests with differently ordered request values will result in duplicated cache entries  A heuristic assumption that the clients will use consistent mechanisms to make requests  thereby resulting in consistent hash values per request is the idea upon which the caching functionality is built upon      Renewal management  The tokens and leases are renewed by the proxy using the secret renewer that is made available via the Vault server s  Go API  https   godoc org github com hashicorp vault api Renewer   Proxy performs all operations in memory and does not persist anything to storage  This means that when the proxy is shut down  all the renewal operations are immediately terminated and there is no way for the proxy to resume renewals after the fact  Note that shutting down the proxy does not indicate revocations of the secrets  instead it only means that renewal responsibility for all the valid unrevoked secrets are no longer performed by the Vault proxy      API      Cache clear  This endpoint clears the cache based on given criteria  To use this API  some information on how the proxy caches values should be known beforehand  Each response that is cached in the proxy will be indexed on some factors depending on the type of request  Those factors can be the  token  that is belonging to the cached response  the  token accessor  of the token belonging to the cached response  the  request path  that resulted in the cached response  the  lease  that is attached to the cached response  the  namespace  to which the cached response belongs to  and a few more  This API exposes some factors through which associated cache entries are fetched and evicted  For listeners without caching enabled  this API will still be available  but will do nothing  there is no cache to clear  and will return a  200  response     Method   Path                      Produces                                                                                POST      proxy v1 cache clear     200 application json          Parameters     type    strings  required     The type of cache entries to evict  Valid   values are  request path    lease    token    token accessor   and  all     If the  type  is set to  all   the  entire cache  is cleared      value    string  required     An exact value or the prefix of the value for   the  type  selected  This parameter is optional when the  type  is set   to  all       namespace    string  optional     This is only applicable when the  type  is set to    request path   The namespace of which the cache entries to be evicted for   the given request path       Sample payload     json      type    token      value    hvs rlNjegSKykWcplOkwsjd8bP9             Sample request     shell session   curl         request POST         data  payload json       http   127 0 0 1 1234 proxy v1 cache clear         Configuration   cache    The presence of the top level  cache  block in any way  including an empty  cache  block   will enable the cache  Note that either  cache static secrets  must be  true  and or  disable caching dynamic secrets  must be  false   otherwise the cache does nothing  The top level  cache  block has the following configuration entries      persist    object  optional     Configuration for the persistent cache      cache static secrets    bool  false     Enables static secret caching when  true       disable caching dynamic secrets    bool  false     Disables dynamic secret caching when  true         Note    When the  cache  block is defined  a  listener  proxy listener  must also be defined in the config  otherwise there is no way to utilize the cache    proxy listener    vault docs agent and proxy proxy listener stanza      Configuration  Persist   These are common configuration values that live within the  persist  block      type    string  required     The type of the persistent cache to use    e g   kubernetes    Note   when using HCL this can be used as the key for   the block  e g   persist  kubernetes          Currently  only  kubernetes    is supported      path    string  required     The path on disk where the persistent cache file   should be created or restored from      keep after import    bool  optional     When set to true  a restored cache file   is not deleted  Defaults to  false       exit on err    bool  optional     When set to true  if any errors occur during   a persistent cache restore  Vault Proxy will exit with an error  Defaults to  true       service account token file    string  optional     When  type  is set to  kubernetes   this configures the path on disk where the Kubernetes service account token can be found  Defaults to   var run secrets kubernetes io serviceaccount token       Configuration   listener       listener    array of objects  required     Configuration for the listeners   There can be one or more  listener  blocks at the top level  Adding a listener enables the  API Proxy   vault docs agent and proxy proxy apiproxy  and enables the API proxy to use the cache  if configured  These configuration values are common to both  tcp  and  unix  listener blocks  Blocks of type  tcp  support the standard  tcp   listener   vault docs configuration listener tcp  options  Additionally  the  role  string option is available as part of the top level of the  listener  block  which can be configured to  metrics only  to serve only metrics  or the default role   default   which serves everything  including metrics       type    string  required     The type of the listener to use  Valid values   are  tcp  and  unix      Note   when using HCL this can be used as the key for the block  e g     listener  tcp              address    string  required     The address for the listener to listen to    This can either be a URL path when using  tcp  or a file path when using    unix   For example   127 0 0 1 8200  or   path to socket   Defaults to    127 0 0 1 8200       tls disable    bool  false     Specifies if TLS will be disabled      tls key file    string  optional     Specifies the path to the private key   for the certificate      tls cert file    string  optional     Specifies the path to the certificate   for TLS       Example configuration  Here is an example of a cache configuration with the optional  persist  block  alongside a regular listener  and a listener that only serves metrics      hcl   Other Vault Proxy configuration blocks        cache    persist       type    kubernetes    path     vault proxy cache     keep after import   true   exit on err   true   service account token file     tmp serviceaccount token        listener  tcp        address    127 0 0 1 8100      tls disable   true    listener  tcp        address    127 0 0 1 3000      tls disable   true     role    metrics only          static secret caching    vault docs agent and proxy proxy caching static secret caching