Difficulty: beginner
Estimated Time: 5 minutes


Nearly all requests to Vault must be accompanied by an authentication token. This includes all API requests, as well as via the Vault CLI and other libraries.

Although a number of auth methods are available, the client is still responsible for managing the lifecycle of its Vault tokens. Therefore, the challenge becomes how to enable authentication to Vault and manage the lifecycle of tokens in a standard way without having to write custom logic.

Vault Agent provides a number of different helper features, specifically addressing the following challenges:

  • Automatic authentication
  • Secure delivery/storage of tokens
  • Lifecycle management of these tokens (renewal & re-authentication)

Depending on the location of your Vault clients and its secret access frequency, you may face some scaling or latency challenge. Even with Vault Performance Replication enabled, the pressure on the storage backend increases as the number of token or lease generation requests increase. Vault 1.0 introduced batch tokens as a solution to relieve some pressure on the storage backend. By design, batch tokens do not support the same level of flexibility and features as service tokens. Therefore, if you need an orphan token for example, you would need service tokens.

To increase the availability of tokens and secrets to the clients, Vault Agent introduced the Caching function.

Vault Agent Caching can cache the tokens and leased secrets proxied through the agent which includes the auto-auth token. This allows for easier access to Vault secrets for edge applications, reduces the I/O burden for basic secrets access for Vault clusters, and allows for secure local access to leased secrets for the life of a valid token.

This lab demonstrates the Vault Agent workflow.

  1. Run Vault Agent
  2. Test Vault Agent Caching
  3. Evict Cached Leases

Vault Agent

Step 1 of 2

Vault Agent Auto-Auth

Vault Agent runs on the client side to automate leases and tokens lifecycle management.

For this scenario, you are going to run the Vault Agent on the same machine as where the Vault server is running. However, the basic working is the same except the host machine address.

Login with root token.

Click on the command () will automatically copy it into the terminal and execute it.

vault login root

First, setup the auth method on the Vault server. In this example, you are going to enable approle auth method.

vault auth enable approle

Create a policy named, "token_update" which is defined by the token_update.hcl file.

vault policy write token_update token_update.hcl

Execute the following command to create a role named, "apps" with token_update policy attached.

vault write auth/approle/role/apps policies="token_update"

Now, generate a role ID and stores it in a file named, "roleID".

vault read -format=json auth/approle/role/apps/role-id \
        | jq  -r '.data.role_id' > roleID

The approle auth method allows machines or apps to authenticate with Vault using Vault-defined roles. The generated roleID is equivalent to username.

Also, generate a secret ID and stores it in the "secretID" file.

vault write -f -format=json auth/approle/role/apps/secret-id \
        | jq -r '.data.secret_id' > secretID

The generated secretID is equivalent to a password.

Refer to the AppRole Pull Authentication guide to learn more.

Vault Agent Configuration

Examine the Vault Agent configuration file, agent-config.hcl.

exit_after_auth = false
pid_file = "./pidfile"

auto_auth {
   method "approle" {
       mount_path = "auth/approle"
       config = {
           role_id_file_path = "roleID"
           secret_id_file_path = "secretID"
           remove_secret_id_file_after_reading = false

   sink "file" {
       config = {
           path = "approleToken"

vault {
   address = ""

The auto_auth block points to the approle auth method, and the acquired token gets stored in approleToken file which is the sink location.

Execute the following command to start the Vault Agent with debug logs.

vault agent -config=agent-config.hcl -log-level=debug

The agent log should include the following messages:

[INFO]  sink.file: creating file sink
[INFO]  sink.file: file sink configured: path=approleToken
[INFO]  auth.handler: starting auth handler
[INFO]  auth.handler: authenticating
[INFO]  sink.server: starting sink server
[INFO]  auth.handler: authentication successful, sending token to sinks
[INFO]  auth.handler: starting renewal process
[INFO]  sink.file: token written: path=approleToken

The acquired client token is now stored in the approleToken file. Your applications can read the token from approleToken and use it to invoke the Vault API.

Click the + next to the opened Terminal, and select Open New Terminal to open another terminal.

New Terminal

Execute the following command to verify the token information.

export VAULT_ADDR=''

vault token lookup $(cat approleToken)

Verify that the token has the token_update policy attached.

Key                  Value
---                  -----
display_name         approle
entity_id            f06b5047-6174-eda5-8530-d067c77e26bc
expire_time          2019-05-19T01:32:26.451100637Z
explicit_max_ttl     0s
id                   s.YKo3MLA6dSshKgeStGuIxIsJ
meta                 map[role_name:apps]
path                 auth/approle/login
policies             [default token_update]

You should be able to create a token using this token (permitted by the token_update policy).

VAULT_TOKEN=$(cat approleToken) vault token create