{"id":18709457,"url":"https://github.com/joemiller/vault-token-helper","last_synced_at":"2025-04-12T10:35:26.228Z","repository":{"id":38313824,"uuid":"189745278","full_name":"joemiller/vault-token-helper","owner":"joemiller","description":"@Hashicorp Vault Token Helper for macOS, Linux and Windows with support for secure token storage and multiple Vault servers 🔐","archived":false,"fork":false,"pushed_at":"2023-04-05T08:59:10.000Z","size":264,"stargazers_count":109,"open_issues_count":15,"forks_count":11,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-10T07:56:00.145Z","etag":null,"topics":["credentials","hashicorp-vault","helper","helper-tool","keychain","keyring","linux","macos","token","vault","windows"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/joemiller.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-06-01T14:57:26.000Z","updated_at":"2025-04-07T07:48:03.000Z","dependencies_parsed_at":"2024-06-18T22:56:48.687Z","dependency_job_id":"8e480361-d521-490e-9845-a5136e492d92","html_url":"https://github.com/joemiller/vault-token-helper","commit_stats":null,"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joemiller%2Fvault-token-helper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joemiller%2Fvault-token-helper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joemiller%2Fvault-token-helper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joemiller%2Fvault-token-helper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/joemiller","download_url":"https://codeload.github.com/joemiller/vault-token-helper/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248553969,"owners_count":21123557,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["credentials","hashicorp-vault","helper","helper-tool","keychain","keyring","linux","macos","token","vault","windows"],"created_at":"2024-11-07T12:27:37.689Z","updated_at":"2025-04-12T10:35:25.980Z","avatar_url":"https://github.com/joemiller.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"vault-token-helper\n==================\n\n![main](https://github.com/joemiller/vault-token-helper/workflows/main/badge.svg)\n\nA @hashicorp Vault [token helper](https://www.vaultproject.io/docs/commands/token-helper.html) with\nsupport for native secret storage on macOS, Linux, and Windows.\n\nFeatures\n--------\n\nStore and retrieve tokens for multiple Vault (`$VAULT_ADDR`) instances, simplifying operators'\nworkflows when working with multiple Vaults.\n\nSupported backends:\n\n* macOS Keychain\n* Linux (DBus Secret Service compatible backends, eg: Gnome Keyring)\n* Windows (WinCred)\n* [pass](https://www.passwordstore.org/) (GPG)\n\nQuickstart (macOS)\n------------------\n\nInstall:\n\n    brew install joemiller/taps/vault-token-helper\n\nConfigure Vault to use the token helper. This will create the `~/.vault` config file:\n\n    vault-token-helper enable\n\nAuthenticate to a Vault instance to encrypt and store a new token locally, for example\nwith the Okta auth backend:\n\n    export VAULT_ADDR=https://vault:8200\n    vault login -method=okta username=joe@dom.tld\n\nOr to store an existing token:\n\n    export VAULT_ADDR=https://vault:8200\n    vault login\n\n    Token (will be hidden): \u003cpaste token\u003e\n\nList saved tokens with extended status output:\n\n    vault-token-helper list -e\n\nKeep reading for further details and installation methods.\n\nInstall\n-------\n\n### One-line install\n\n| OS                              | Command                                          |\n|---------------------------------|--------------------------------------------------|\n| macOS                           | `brew install joemiller/taps/vault-token-helper` |\n| Linux\u003cbr\u003e(LinuxBrew) *untested* | `brew install joemiller/taps/vault-token-helper` |\n\n### Linux packages\n\n| Format | Arch  |\n|--------|-------|\n| [rpm]  | amd64 |\n| [deb]  | amd64 |\n\n### Pre-built binaries\n\n| OS      | Arch  | binary                                |\n|---------|-------|---------------------------------------|\n| macOS   | amd64 | [vault-token-helper][latest-binaries] |\n| Linux   | amd64 | [vault-token-helper][latest-binaries] |\n| Windows | amd64 | [vault-token-helper][latest-binaries] |\n\n[latest-binaries]: https://github.com/joemiller/vault-token-helper/releases/latest\n[rpm]: https://github.com/joemiller/vault-token-helper/releases/latest\n[deb]: https://github.com/joemiller/vault-token-helper/releases/latest\n\n### From source\n\nClone this repo and compile for the current architecture:\n\n    make build\n\n### Verifying releases\n\nmacOS binaries are CodeSign'd with a certificate from Apple.\n\nAdditionally all releases are signed using this project's GPG key:\n\n* Subject: `vault-token-helper (github.com/joemiller/vault-token-helper project key) \u003cvault-token-helper@joemiller.me\u003e`\n* key-ID `37F9D1272278CD32`\n* fingerprint `5EF2 2550 7053 ACC2 728A  A51C 37F9 D127 2278 CD32`.\n\nThe key can be fetched from most keyservers:\n\n    gpg --recv-keys 37F9D1272278CD32\n\n[Download](https://github.com/joemiller/vault-token-helper/releases/latest) and verify the signature\non the checksum file:\n\n    gpg --verify vault-token-helper_0.2.0_checksums.txt.sig vault-token-helper_0.2.0_checksums.txt\n\nAfter verifying the checksum file's signature use `shasum` to verify the checksums of the\nrelease artifacts:\n\n    shasum --check vault-token-helper_0.2.0_checksums.txt\n\nUsage\n-----\n\n### Pre-Reqs\n\n`vault-token-helper` will attempt to detect the best available token storage backend.\nOn macOS this will be the Keychain app, on Windows the native credential store, and\non most Linux distros the DBus Secret-Service API (common packages implementing this are\nGnome Keyring and Seahorse).\n\nYou may need to install a compatible credential storage service on Linux. For example,\non Arch Linux with a vanilla desktop you may need to install `gnome-keyring`.\n\nAlternatively, the cross-platform, GPG-based [pass](https://www.passwordstore.org/)\nutility can also be used. You must initialize `pass` (`pass init`) with a GPG key before\nusing `vault-token-helper`.\n\n### Configure Vault\n\nInstall `vault-token-helper` then run:\n\n    vault-token-helper enable\n\nThis creates (overwrites) the `$HOME/.vault` config file used by the `vault` CLI.\n\nAlternatively, edit the file and specify the full path to the `vault-token-helper` binary:\n\n    token_helper = \"/install/path/to/vault-token-helper\"\n\n### Configure vault-token-helper\n\nFor most installations the defaults should be sufficient.\n\nAn optional configuration file located at `$HOME/.vault-token-helper.yaml` can be used to\noverride the defaults.\n\nA fully annotated example config file is available in [./vault-token-helper.annotated.yaml](./vault-token-helper.annotated.yaml)\n\n### Login to Vault\n\nSet `VAULT_ADDR` to the URL of your Vault instance and run `vault` commands like normal. For example,\nto login and store a token on a Vault instance with the Okta auth plugin enabled:\n\n    VAULT_ADDR=https://vault:8200 vault login -method=okta username=joe@dom.tld\n\nOr to store an existing token:\n\n    $ VAULT_ADDR=https://vault:8200 vault login\n    Token (will be hidden): \u003cpaste token\u003e\n\nUpon successful authentication the Vault token will be stored securely in the platform's\nsecrets store.\n\nSupport for storing tokens from multiple Vault instances is implemented. Change the `VAULT_ADDR`\nenvironment variable to switch between Vault instances.\n\nThe `VAULT_NAMESPACE` environment variable is also supported.\n\n### Additional commands\n\nThe standard `store`, `get`, and `erase` commands are implemented according to the vault token\nhelper [spec](https://www.vaultproject.io/docs/commands/token-helper.html).\n\nThere are a few additional commands:\n\n* `enable`: Enable the vault-token-helper by (over)writing the ~/.vault config file.\n* `backends`: List the available secret storage backends on the current platform.\n* `list`: List tokens. Add `--extended/-e` flag to lookup additional details about the stored\n    token by quering the Vault instance's token lookup API.\n\n```console\n$ vault-token-helper list --extended\n\nVAULT_ADDR                       display_name      ttl         renewable  policies\n----------                       ------------      ---         ---------  --------\nhttps://vault-prod.dom.tld:8200  okta-joe@dom.tld  527h46m18s  true       [admin default]\nhttps://vault-dev.dom.tld:8200   okta-joe@dom.tld  275h13m17s  true       [admin default]\nhttps://localhost                ** ERROR **       Get https://localhost/v1/auth/token/lookup-self: dial tcp 127.0.0.1:443: connect: connection refused\n```\n\nSupport\n-------\n\nPlease open a GitHub [issue](https://github.com/joemiller/vault-token-helper/issues).\n\nSetting the `KEYRING_DEBUG` environment variable to any value will produce additional output\nthat may be useful for debugging common issues. Please set this variable and then\nrun a command such as `vault-token-helper list`. Include the debug output in your issue.\n\nDevelopment\n-----------\n\n### Tests\n\nRun tests: `make test`.\n\nThere is test coverage in `pkg/store` covering all of the supported backends. Additionally, there\nis an integration test in the `cmd` package.\n\nSome tests are platform specific and difficult to test outside of a full desktop environment\ndue to interactive elements such as password prompts. To aid in development there are Vagrant\nVMs with GUIs enabled in the `./vagrant/` directory. See the\n[./vagrant/README.md](./vagrant/README.md) for further details.\n\nThe most complete way to run all tests would be to run `make test` under each platform (macOS, Linux, Windows).\n\n### CI/CD\n\n[Github Actions](https://github.com/joemiller/vault-token-helper/actions) is used for CI/CD.\n\nTests are run on pull requests and versioned releases are generated on all successful main branch\nbuilds.\n\nSome tests are not run in CI/CD due to requiring an interactive desktop such as the Linux\nDBus Secret Service backend.\n\n### Release Management\n\nReleases are cut automatically on all successful main branch builds. This project uses\n[autotag](https://github.com/pantheon-systems/autotag) and [goreleaser](https://goreleaser.com/) to\nautomate this process.\n\nSemver (`vMajor.Minor.Patch`) is used for versioning and releases. By default, autotag will bump the\npatch version on a successful main build, eg: `v1.0.0` -\u003e `v1.0.1`.\n\nTo bump the major or minor release instead, include `[major]` or `[minor]` in the commit message.\nRefer to the autotag [docs](https://github.com/pantheon-systems/autotag#incrementing-major-and-minor-versions)\nfor more details.\n\nInclude `[skip ci]` in the commit message to prevent a new version from being released. Only use this\nfor things like documentation updates.\n\nA local release can be built and signed with a copy of the project GPG key's signing subkey:\n\n```console\n$ GPG_KEY=\"$(cat vault-token-helper.signing-key.gpg | base64)\" make release\n\n# or a snapshot build:\n\n$ GPG_KEY=\"$(cat vault-token-helper.signing-key.gpg | base64)\" make snapshot\n```\n\n#### Apple codesign\n\nIn order to avoid macOS keychain from always prompting for passwords the macOS binaries\nare codesigned with a cert issued by Apple.\n\nTODO\n----\n\n*after v0.1.0:*\n\n* [x] The wincred lib used by 99designs/keyring has more configuration options available. Make these available in 99designs/keyring and vault-token-helper.\n* [x] add a flag like `--extended` to `list` that will query vault for additional token info, eg: valid/invalid, ttl, policies\n* ci/cd:\n  * [x] `sign` checksum.txt and assets in goreleaser.yaml GPG key\n  * [x] apple `codesign` the macos binaries\n  * [ ] 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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoemiller%2Fvault-token-helper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjoemiller%2Fvault-token-helper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoemiller%2Fvault-token-helper/lists"}