Vault Token Helper is a tool designed to simplify token management for multiple Vault servers across macOS, Linux, and Windows. It provides secure storage for tokens using platform-specific credential stores or GPG-based pass integration.
Key Features:
Secure token storage on macOS (Keychain), Linux (DBus Secret Service compatible backends like Gnome Keyring), Windows (WinCred), and via the pass utility.
Support for managing tokens across multiple Vault instances, allowing operators to switch between environments seamlessly.
Built-in commands such as enable to configure Vault CLI integration, backends to list supported storage methods, and list -e to display extended token details by querying Vault.
Automatic detection of the best available credential storage backend for each platform.
Audience & Benefit:
Ideal for DevOps engineers, system administrators, and security teams working with HashiCorp Vault. By automating secure token storage and retrieval, this tool streamlines workflows when managing multiple Vault instances, enhances security by keeping tokens encrypted at rest, and reduces the risk of accidental credential exposure.
README
vault-token-helper
A @hashicorp Vault token helper with
support for native secret storage on macOS, Linux, and Windows.
Features
Store and retrieve tokens for multiple Vault ($VAULT_ADDR) instances, simplifying operators'
workflows when working with multiple Vaults.
Supported backends:
macOS Keychain
Linux (DBus Secret Service compatible backends, eg: Gnome Keyring)
vault-token-helper will attempt to detect the best available token storage backend.
On macOS this will be the Keychain app, on Windows the native credential store, and
on most Linux distros the DBus Secret-Service API (common packages implementing this are
Gnome Keyring and Seahorse).
You may need to install a compatible credential storage service on Linux. For example,
on Arch Linux with a vanilla desktop you may need to install gnome-keyring.
Alternatively, the cross-platform, GPG-based pass
utility can also be used. You must initialize pass (pass init) with a GPG key before
using vault-token-helper.
Configure Vault
Install vault-token-helper then run:
vault-token-helper enable
This creates (overwrites) the $HOME/.vault config file used by the vault CLI.
Alternatively, edit the file and specify the full path to the vault-token-helper binary:
Set VAULT_ADDR to the URL of your Vault instance and run vault commands like normal. For example,
to login and store a token on a Vault instance with the Okta auth plugin enabled:
Setting the KEYRING_DEBUG environment variable to any value will produce additional output
that may be useful for debugging common issues. Please set this variable and then
run a command such as vault-token-helper list. Include the debug output in your issue.
Development
Tests
Run tests: make test.
There is test coverage in pkg/store covering all of the supported backends. Additionally, there
is an integration test in the cmd package.
Some tests are platform specific and difficult to test outside of a full desktop environment
due to interactive elements such as password prompts. To aid in development there are Vagrant
VMs with GUIs enabled in the ./vagrant/ directory. See the
./vagrant/README.md for further details.
The most complete way to run all tests would be to run make test under each platform (macOS, Linux, Windows).
Tests are run on pull requests and versioned releases are generated on all successful main branch
builds.
Some tests are not run in CI/CD due to requiring an interactive desktop such as the Linux
DBus Secret Service backend.
Release Management
Releases are cut automatically on all successful main branch builds. This project uses
autotag and goreleaser to
automate this process.
Semver (vMajor.Minor.Patch) is used for versioning and releases. By default, autotag will bump the
patch version on a successful main build, eg: v1.0.0 -> v1.0.1.
To bump the major or minor release instead, include [major] or [minor] in the commit message.
Refer to the autotag docs
for more details.
Include [skip ci] in the commit message to prevent a new version from being released. Only use this
for things like documentation updates.
A local release can be built and signed with a copy of the project GPG key's signing subkey:
$ GPG_KEY="$(cat vault-token-helper.signing-key.gpg | base64)" make release
# or a snapshot build:
$ GPG_KEY="$(cat vault-token-helper.signing-key.gpg | base64)" make snapshot
Apple codesign
In order to avoid macOS keychain from always prompting for passwords the macOS binaries
are codesigned with a cert issued by Apple.
TODO
after v0.1.0:
The wincred lib used by 99designs/keyring has more configuration options available. Make these available in 99designs/keyring and vault-token-helper.
add a flag like --extended to list that will query vault for additional token info, eg: valid/invalid, ttl, policies
ci/cd:
sign checksum.txt and assets in goreleaser.yaml GPG key
apple codesign the macos binaries
linux tests, figure out how to test dbus secret-service in headless CI. probably need a stub to connect to Dbus and provide the 'prompt' service
