Use a custom token helper

A token helper is a program or script that saves, retrieves, or erases a saved authentication token.

By default, the Vault CLI includes a token helper that caches tokens from any enabled authentication backend in a ~/.vault-token file. You can customize the caching behavior with a custom token helper.

Step 1: Script your helper

Your token helper must accept a single command-line argument:

Argument	Action
`get`	Fetch and print a cached authentication token to `stdout`
`store`	Read an authentication token from `stdin` and save it in a secure location
`erase`	Delete a cached authentication token

You can manage the authentication tokens in whatever way you prefer, but your helper must adhere to following output requirements:

Limit stdout writes to token strings.
Write all error messages to stderr.
Write all non-error and non-token output to syslog or a log file.
Return the status code 0 on success.
Return non-zero status codes for errors.

Step 2: Configure Vault

To configure a custom token helper, edit (or create) a CLI configuration file called .vault under your home directory and set the token_helper parameter with the fully qualified path to your new helper:

echo 'token_helper = "/path/to/token/helper.sh"' >> ${HOME}/.vault

Make sure to use UTF-8 encoding (ascii) or Vault may complain about invalid characters when reading the configuration file:

'token_helper = "\\path\\to\\token\\helper.ps1"' | `
Out-File -FilePath ${env:USERPROFILE}/.vault -Encoding ascii -Append

Tip

Make sure the script is executable by the Vault binary.

Example token helper

The following token helper manages tokens in a JSON file in the home directory called .vault_tokens.

The helper relies on the $VAULT_ADDR environment variable to store and retrieve tokens from different Vault servers.

#!/bin/bash

function write_error(){ >&2 echo $@; }

# Customize the hash key for tokens. Currently, we remove the strings
# 'https://', '.', and ':' from the passed address (Vault address environment
# by default) because jq has trouble with special characeters in JSON field
# names
function createHashKey {
  
  local key=""

  if [[ -z "${1}" ]] ; then key="${VAULT_ADDR}" 
  else                      key="${1}"
  fi
  
  # We index the token according to the Vault server address by default so
  # return an error if the address is empty
  if [[ -z "${key}" ]] ; then
    write_error "Error: VAULT_ADDR environment variable unset."
    exit 100
  fi

  key=${key//"http://"/""}
  key=${key//"."/"_"}
  key=${key//":"/"_"}

  echo "addr-${key}"
}

TOKEN_FILE="${HOME}/.vault_token"
KEY=$(createHashKey)
TOKEN="null"

# If the token file does not exist, create it
if [ ! -f ${TOKEN_FILE} ] ; then
   echo "{}" > ${TOKEN_FILE}
fi

case "${1}" in
    "get")

      # Read the current JSON data and pull the token associated with ${KEY}
      TOKEN=$(cat ${TOKEN_FILE} | jq --arg key "${KEY}" -r '.[$key]')
      
      # If the token != to the string "null", print the token to stdout 
      # jq returns "null" if the key was not found in the JSON data
      if [ ! "${TOKEN}" == "null" ] ; then
        echo "${TOKEN}"
      fi
      exit 0
    ;;

    "store")
      
      # Get the token from stdin
      read TOKEN

      # Read the current JSON data and add a new entry
      JSON=$(
        jq                      \
        --arg key "${KEY}"      \
        --arg token "${TOKEN}"  \
        '.[$key] = $token' ${TOKEN_FILE}
      )
      
    ;;

    "erase")
      # Read the current JSON data and remove the entry if it exists
      JSON=$(
        jq                      \
        --arg key "${KEY}"      \
        --arg token "${TOKEN}"  \
        'del(.[$key])' ${TOKEN_FILE}
      )
    
    ;;

    *)
      # change to stderr for real code
      write_error "Error: Provide a valid command: get, store, or erase."
      exit 101
esac

# Update the JSON file and return success
echo $JSON | jq "." > ${TOKEN_FILE}
exit 0

<#
.Synopsis
  Vault token helper script
.INPUTS
  Positional/command line argument: get, store, erase
.OUTPUTS
  get: prints a cached authentication token to stdin (if it exists)
  store: no output, updates the token cache
  erase: no output, updates the token cache
#>

<#
.Synopsis
  CreateHashKey
.DESCRIPTION
  Customize the hash key for tokens. Currently, we remove the strings
  'https://', '.', and ':' from the passed address (Vault address environment by
  default) variable to simplify the hash key string
#>
function CreateHashKey {

  Param($address = "${env:VAULT_ADDR}")
  
  # We index the token according to the Vault server address by default so
  # return an error if the address is empty
  if ( -not $address) {
    Write-Error "[Missing value] env:VAULT_ADDR currently unset."
    exit 101
  }

  $key = ${address}.Replace("/","").Replace(".","_").Replace(":","_")
  return ${key}.Replace("http_", "addr-")
}

<#
.Synopsis
  GetTokenCache
.DESCRIPTION
  Read in or create a new token cache and initialize the hash 
#>
function GetTokenCache {

  Param($filename)

  # Read the JSON file (token cache) and initialize the hash data or create an
  # empty hash if the file does not exist yet
  if ( Get-Item -Path "./${filename}" -ErrorAction SilentlyContinue ) {
    $fileData = (Get-Content "${filename}" -Raw | ConvertFrom-Json -AsHashtable)
  } else {
    $fileData = (Write-Output "{}" | ConvertFrom-Json -AsHashtable)
  } 

  return $fileData
}

<#
.Synopsis
  UpdateTokenCache
.DESCRIPTION
  Write the token hash out to the cache 
#>
function UpdateTokenCache {

  Param($filename, $fileData)
  $jsonData = ($fileData | ConvertTo-Json) 

  # Convert the hash to JSON and update the token cache
  $jsonData | Out-File -Encoding ascii "${filename}"

  return
}

$tokenFile = "${env:USERPROFILE}/.vault_token"
$hashData  = (GetTokenCache "${tokenFile}")
$key       = (CreateHashKey)
$token     = $null

switch -Exact -CaseSensitive (${args}[0]) {

  "get" {
    # Print the token to stdin and return success
    Write-Output ${hashData}.${key}
    exit 0
  }

  "store" {
    $token = Read-Host
    # Add the new token to the hash
    $hashData["${key}"] = "${token}" 
  }

  "erase" {
    # Erase the token entry if it exists
    if ($hashData.ContainsKey("${key}") ) {
      $hashData.Remove("${key}")
    }
  }

  Default {
    # The argument was invalid so return an error
    Write-Error "[Invalid argument] Command must be: get, store, or erase."
    exit 102
  }

}

# Update the token cache and return success
UpdateTokenCache ${tokenFile} ${hashData}

exit 0

#!/usr/bin/env ruby

require 'json'

// We index the token according to the Vault server address
// so the VAULT_ADDR variable is required 
unless ENV['VAULT_ADDR']
  STDERR.puts "No VAULT_ADDR environment variable set. Set it and run me again!"
  exit 100
end

// If the token file does not exist, create and initialize the hashmap
begin
  tokens = JSON.parse(File.read("#{ENV['HOME']}/.vault_tokens"))
rescue Errno::ENOENT => e
  # file doesn't exist so create a blank hash for it
  tokens = {}
end

// Get the first command line argument
case ARGV.first
when 'get'
  // Write the token to stdout if it exists
  print tokens[ENV['VAULT_ADDR']] if tokens[ENV['VAULT_ADDR']]
  exit 0
when 'store'
  // Read the token from stdin
  tokens[ENV['VAULT_ADDR']] = STDIN.read
when 'erase'
  // Delete the token entry if it exists
  tokens.delete!(ENV['VAULT_ADDR'])
end


// Update the token file
File.open("#{ENV['HOME']}/.vault_tokens", 'w') { |file| file.write(tokens.to_json) }