{"id":19168416,"url":"https://github.com/bloomberg/vault-auth-spire","last_synced_at":"2025-05-07T14:41:53.635Z","repository":{"id":66125216,"uuid":"217571645","full_name":"bloomberg/vault-auth-spire","owner":"bloomberg","description":"vault-auth-spire is an authentication plugin for Hashicorp Vault which allows logging into Vault using a Spire provided SVID.","archived":false,"fork":false,"pushed_at":"2023-07-05T20:50:49.000Z","size":200,"stargazers_count":41,"open_issues_count":13,"forks_count":7,"subscribers_count":7,"default_branch":"develop","last_synced_at":"2025-04-19T23:31:58.949Z","etag":null,"topics":["authn","go","plugin","spiffe","spire","vault"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bloomberg.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-10-25T16:15:36.000Z","updated_at":"2025-03-07T01:29:17.000Z","dependencies_parsed_at":null,"dependency_job_id":"42b50024-4b70-4cba-ad61-075b8edb64bf","html_url":"https://github.com/bloomberg/vault-auth-spire","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bloomberg%2Fvault-auth-spire","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bloomberg%2Fvault-auth-spire/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bloomberg%2Fvault-auth-spire/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bloomberg%2Fvault-auth-spire/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bloomberg","download_url":"https://codeload.github.com/bloomberg/vault-auth-spire/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252897434,"owners_count":21821437,"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":["authn","go","plugin","spiffe","spire","vault"],"created_at":"2024-11-09T09:42:35.809Z","updated_at":"2025-05-07T14:41:53.612Z","avatar_url":"https://github.com/bloomberg.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SPIRE Vault Authentication Plugin\n\nSPIRE Vault Authentication Plugin is an authentication plugin for [Hashicorp Vault](https://www.vaultproject.io) which allows logging into Vault using a SPIRE provided SVID.\n\n## Menu\n\n- [Rationale](#rationale)\n- [Quick start](#quick-start)\n- [Building](#building)\n- [Installation](#installation)\n- [Contributions](#contributions)\n- [License](#license)\n- [Code of Conduct](#code-of-conduct)\n- [Security Vulnerability Reporting](#security-vulnerability-reporting)\n\n## Rationale\n\nThis plugin exists to allow SPIRE authenticated workloads to authenticate with Vault using their SPIRE provided SVID, and then interact with Vault as they would if they authenticated with Vault via any other Vault supported authentication mechanism. The intention is to support the following login scenerio\n```\n$\u003e vault write auth/spire/login jwt=\"\u003cjwt svid\u003e\"\n$\u003e vault write auth/spire/login -client-cert=svid.0.pem  -client-key=svid.0.key\" \u003c-- TLS connection using X509-SVID\n```\n\nwhere the SVID contains a valid SpiffeID which is used to determine which policies to apply during the Vault session. \n\nCurrently the plugin is coded to accept X509-SVID documents via the non-TLS method but that is just for speed of development purposes - it will not be true in a released version. See [#12](https://github.com/bloomberg/vault-auth-spire/issues/12) for a discussion on accepting X509-SVIDs.\n\nDuring the login process the provided SVID will be verified against CA trust bundles known to the plugin. The SVID must have been generated using one of the known CA trust bundles. As per the rules in Spiffe regarding [trust domains and bundles](https://github.com/spiffe/spiffe/blob/master/standards/SPIFFE_Trust_Domain_and_Bundle.md), each trust domain known to the plugin will use 1 or more public CAs to verify SVIDs generated in that domain. The `vault-auth-spire` plugin supports the configuration of multiple trust domains, each with 1 or more root or intermediate CAs used to verify the SVIDs. This use of 1 or more CAs allows the plugin to support CA rotation.\n\nThe plugin uses Trust Sources to manage from where it receives trusted CAs. There are two types of trust sources: read from file and pushed from SPIRE. The trust sources are configured in the plugin settings and will be used to acquire trust CAs. The plugin can simultaneously acquire trust CAs from file and SPIRE.\n\n### Trust Sources\n\nA Trust Source provides a way for `vault-auth-spire` to acquire trust CAs. There are two types of trust sources: from file and SPIRE. Both types of trust sources can be used at the same time.\n\n#### File Trust Source\n\nWhen using a File Trust Source one needs to map a Trust Domain to one or more files containing the trusted CAs for that domain. This information is provided to the plugin via its settings file.\n\n```json\n{\n  \"trustsource\": {\n    \"file\": {\n      \"domains\": {\n        \"spiffe://some.domain.com\": [\"/path/to/ca/for/domain.crt\", \"/path/to/secondary/ca/for/domain.crt\"],\n        \"spiffe://some.otherdomain.com\": [\"/path/to/ca/for/otherdomain.crt\"]\n      }\n    }\n  }\n}\n```\n\nEach domain can be provided with one or more trusted CA files and each CA file can contain one or more actual certificates. The full set of certificates found across all files will be used to verify SVIDs claiming to be within the configured domain. This structure allows the plugin to fully support certificate rotation.\n\n#### SPIRE Trust Source\n\n**This is still under development and some details are unknown at this time**\n\nWhen using the SPIRE Trust Source one needs to provide enough information for the plugin to connect to SPIRE and retreive its known trust CAs. The information is provided to the plugin via its settings file\n\n```json\n{\n  \"trustsource\": {\n    \"spire\": ...unknown at the moment...\n  }\n}\n```\n\nCurrent ideas for this trust source include\n\n1. Support connecting to multiple SPIRE instances (agents or servers) to allow for broad authentication, particularly where different systems are using the same Vault instance.\n2. Support saving the SPIRE provided CAs to disk so they can be used if the plugin is unable to connect to a SPIRE instance. This will help limit the blast radius of a failing SPIRE connection.\n\n## Quick Start\n\n## Building\n\nThe plugin can be built using standard `go` commands or simply by using the provided [`Makefile`](Makefile).\n\n```\n$\u003e make build\nGOOS=linux GOARCH=amd64 go build -o vault-auth-spire cmd/plugin/vault-auth-spire.go\n```\n\n## Installation\n\nThe plugin is installed and registered just like [any other Vault plugin](https://www.vaultproject.io/docs/internals/plugins.html#plugin-registration). It should be placed in the appropriate plugin directory and registered in the catalog. When registering the plugin it is necessary to provide the location of the plugin settings file.\n\n```\n$\u003e vault write sys/plugins/catalog/auth/spire \\\n    sha_256=\"$(shasum -a 256 '/path/to/plugin/vault-auth-spire' | cut -d' ' -f1)\" \\\n    command=\"vault-auth-spire\" \\\n    args=\"--settings-file=/path/to/settings/vault-auth-spire-settings.json\"\n```\n\nBefore usage all plugins need to be enabled\n\n```\n$\u003e vault auth enable \\\n    -path=\"spire\" \\\n    -plugin-name=\"spire\" plugin\n```\n\n## Contributions\n\nWe :heart: contributions.\n\nHave you had a good experience with this project? Why not share some love and contribute code, or just let us know about any issues you had with it?\n\nWe welcome issue reports [here](../../issues); be sure to choose the proper issue template for your issue, so that we can be sure you're providing the necessary information.\n\nBefore sending a [Pull Request](../../pulls), please make sure you read our\n[Contribution Guidelines](https://github.com/bloomberg/.github/blob/master/CONTRIBUTING.md).\n\n## License\n\nPlease read the [LICENSE](LICENSE) file.\n\n## Code of Conduct\n\nThis project has adopted a [Code of Conduct](https://github.com/bloomberg/.github/blob/master/CODE_OF_CONDUCT.md).\nIf you have any concerns about the Code, or behavior which you have experienced in the project, please\ncontact us at opensource@bloomberg.net.\n\n## Security Vulnerability Reporting\n\nIf you believe you have identified a security vulnerability in this project, please send email to the project\nteam at opensource@bloomberg.net, detailing the suspected issue and any methods you've found to reproduce it.\n\nPlease do NOT open an issue in the GitHub repository, as we'd prefer to keep vulnerability reports private until\nwe've had an opportunity to review and address them.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbloomberg%2Fvault-auth-spire","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbloomberg%2Fvault-auth-spire","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbloomberg%2Fvault-auth-spire/lists"}