• HashiCorp Developer

  • HashiCorp Cloud Platform
  • Terraform
  • Packer
  • Consul
  • Vault
  • Boundary
  • Nomad
  • Waypoint
  • Vagrant
Vault
  • Install
  • Tutorials
  • Documentation
  • API
  • Integrations
  • Try Cloud(opens in new tab)
  • Sign up
Vault Home

Documentation

Skip to main content
  • Documentation
  • What is Vault?
  • Use Cases

  • Browser Support
  • Installing Vault
    • Overview
    • agent
    • debug
    • delete
    • list
    • login
    • monitor
    • namespace
    • path-help
    • read
    • server
    • ssh
    • status
    • unwrap
    • version
    • version-history
    • write
    • Token Helpers

  • Vault Integration Program
  • Vault Interoperability Matrix
  • Troubleshoot






  • Glossary


  • Resources

  • Tutorial Library
  • Certifications
  • Community Forum
    (opens in new tab)
  • Support
    (opens in new tab)
  • GitHub
    (opens in new tab)
  1. Developer
  2. Vault
  3. Documentation
  4. Commands (CLI)
  5. Token Helpers
  • Vault
  • v1.11.x
  • v1.10.x
  • v1.9.x
  • v1.8.x
  • v1.7.x
  • v1.6.x
  • v1.5.x
  • v1.4.x

»Token Helpers

A token helper is an external program that Vault calls to save, retrieve or erase a saved token. The token helper could be a very simple script or a more complex program depending on your needs. The interface to the external token helper is extremely simple.

By default the Vault CLI provides a built in tool for authenticating with any of the enabled authentication backends. Once authenticated, the CLI will store the generated token on disk in the ~/.vault-token file. By using a token helper, this default functionality can be changed.

Configuration

To configure a token helper, edit (or create) the file ~/.vault and add a line similar to:

token_helper = "/path/to/token/helper.sh"

You will need to use the fully qualified path to the token helper script. The script should be executable.

Developing a Token Helper

The interface to a token helper is extremely simple: the script is passed with one argument that could be get, store or erase. If the argument is get, the script should do whatever work it needs to do to retrieve the stored token and then print the token to STDOUT. If the argument is store, Vault is asking you to store the token. Finally, if the argument is erase, your program should erase the stored token.

If your program succeeds, it should exit with status code 0. If it encounters an issue that prevents it from working, it should exit with some other status code. You should write a user-friendly error message to STDERR. You should never write anything other than the token to STDOUT, as Vault assumes whatever it gets on STDOUT is the token.

Example Token Helper

This is an example token helper written in Ruby that stores and retrieves tokens in a json file called ~/.vault_tokens. The key is the environment variable \$VAULT_ADDR, this allows the Vault user to easily store and retrieve tokens from a number of different Vault servers.

#!/usr/bin/env ruby

require 'json'

unless ENV['VAULT_ADDR']
  STDERR.puts "No VAULT_ADDR environment variable set. Set it and run me again!"
  exit 100
end

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

case ARGV.first
when 'get'
  print tokens[ENV['VAULT_ADDR']] if tokens[ENV['VAULT_ADDR']]
  exit 0
when 'store'
  tokens[ENV['VAULT_ADDR']] = STDIN.read
when 'erase'
  tokens.delete!(ENV['VAULT_ADDR'])
end

File.open("#{ENV['HOME']}/.vault_tokens", 'w') { |file| file.write(tokens.to_json) }
Edit this page on GitHub

On this page

  1. Token Helpers
  2. Configuration
  3. Developing a Token Helper
Give Feedback(opens in new tab)
  • Certifications
  • System Status
  • Terms of Use
  • Security
  • Privacy
  • Trademark Policy
  • Trade Controls
  • Give Feedback(opens in new tab)