Utilizes Spiffe JWT authentication with Hashicorp Vault for secretless authentication.

# SPIFFE Vault

Integrates [SPIFFE][spiffe] SVID authentication with [Hashicorp Vault][hashivault] to retrieve a `VAULT_TOKEN`.

[![Go CI](https://github.com/philips-labs/spiffe-vault/actions/workflows/golang.yml/badge.svg)](https://github.com/philips-labs/spiffe-vault/actions/workflows/golang.yml)
[![Go Report Card](https://goreportcard.com/badge/github.com/philips-labs/spiffe-vault)](https://goreportcard.com/report/github.com/philips-labs/spiffe-vault)
[![codecov](https://codecov.io/gh/philips-labs/spiffe-vault/branch/main/graph/badge.svg)](https://codecov.io/gh/philips-labs/spiffe-vault)

## Example usecases

- Read secrets from Hashicorp Vault [Hashicorp Vault][hashivault] without providing a secret to authenticate against [Hashicorp Vault][hashivault]. Instead we will be using a [SPIFFE][spiffe] SVID to authenticate ourself against [Hashicorp Vault][hashivault].

- Perform secretless/keyless code signing by utilizing the [Hashicorp Vault Transit engine](https://www.vaultproject.io/docs/secrets/transit) as a software defined HSM. This resolves the issue of having signing keys on a local machine as well resolves the issue of managing secrets to access the signing keys. Again we utilize the [SPIFFE][spiffe] SVID to authenticate against Hashicorp Vault.

[hashivault]: https://vaultproject.org "hashicorp Vault"
[spiffe]: https://spiffe.io "SPIFFE"

## Build

### Compile

```bash
make build
```

### Docker

Using the default `DOCKER_HOST` on your system (usually `unix:///var/run/docker.sock`), you can build the docker image with:

```bash
make image
```

Using e.g. the colima `DOCKER_HOST` (usually `unix:///Users/marco/.colima/default/docker.sock`), you can build the docker image with:

```bash
DOCKER_HOST=unix:///Users/marco/.colima/default/docker.sock make image
```

## Use

### Basic

```bash
$ export VAULT_ADDR=http://localhost:8200
$ bin/spiffe-vault auth -role my-role
# Export following environment variable to authenticate to Hashicorp Vault
export VAULT_TOKEN=s.IK1LBrCGXFQDAgawmhNLbcDH
```

### Advanced

Depending on the shell you are using you can automatically export the variable.

<details>
  <summary>bash</summary>

```bash
$ export VAULT_ADDR=http://localhost:8200
$ echo "$(bin/spiffe-vault auth -role my-role)" > /tmp/spiffe-vault
$ source /tmp/spiffe-vault
$ vault kv get secrets/my-key
====== Metadata ======
Key              Value
---              -----
created_time     2021-08-24T08:20:54.925866504Z
deletion_time    n/a
destroyed        false
version          1

============= Data =============
Key                       Value
---                       -----
username                  marco
password                  Supers3cr3t!
$ vault token lookup
Key                 Value
---                 -----
accessor            rwpXIHXzbVIMN2TL25Lfssef
creation_time       1629970184
creation_ttl        1m
display_name        jwt-spiffe://dev.localhost/ns/my-app/sa/my-app-backend
entity_id           8904661e-5a9f-3af5-c269-257e8a0a31d0
expire_time         2021-08-26T09:30:44.424072877Z
explicit_max_ttl    0s
id                  s.eOdhqe1hVV0OPS7M0TSeEqjG
issue_time          2021-08-26T09:29:44.424078028Z
meta                map[role:my-role]
num_uses            0
orphan              true
path                auth/jwt/login
policies            [default my-role]
renewable           true
ttl                 13s
type                service
$ vault token renew
Key                  Value
---                  -----
token                s.f1mFvr0TdEuvmfcZT0jBLCc5
token_accessor       vxginlb81XMEIPefLpRz1P24
token_duration       1m
token_renewable      true
token_policies       ["default" "my-role"]
identity_policies    []
policies             ["default" "my-role"]
token_meta_role      my-role
$ vault token lookup
Key                  Value
---                  -----
accessor             vxginlb81XMEIPefLpRz1P24
creation_time        1629970320
creation_ttl         1m
display_name         jwt-spiffe://dev.localhost/ns/my-app/sa/my-app-backend
entity_id            8904661e-5a9f-3af5-c269-257e8a0a31d0
expire_time          2021-08-26T09:33:53.57444787Z
explicit_max_ttl     0s
id                   s.f1mFvr0TdEuvmfcZT0jBLCc5
issue_time           2021-08-26T09:32:00.135787193Z
last_renewal         2021-08-26T09:32:53.574447972Z
last_renewal_time    1629970373
meta                 map[role:my-role]
num_uses             0
orphan               true
path                 auth/jwt/login
policies             [default my-role]
renewable            true
ttl                  56s
type                 service
$ vault write transit/sign/my-key input="$(echo stuff | base64)"
Key            Value
---            -----
key_version    1
signature      vault:v1:MEUCIFAWmHPyLJ6V0mjMgqr5UnV40bkCEUEGqApcYI54VAPIAiEAqyG2VkFc2wpYs/n47mK4vgfTVbXjWJzMM7Fxr/bR7LE=
$ vault write transit/verify/my-key input="$(echo stuff | base64)" signature=vault:v1:MEUCIFAWmHPyLJ6V0mjMgqr5UnV40bkCEUEGqApcYI54VAPIAiEAqyG2VkFc2wpYs/n47mK4vgfTVbXjWJzMM7Fxr/bR7LE=
```

</details>

<details>
  <summary>zsh</summary>

```zsh
$ export VAULT_ADDR=http://localhost:8200
$ source <(bin/spiffe-vault auth -role my-role)
$ vault kv get secrets/my-key
====== Metadata ======
Key              Value
---              -----
created_time     2021-08-24T08:20:54.925866504Z
deletion_time    n/a
destroyed        false
version          1

============= Data =============
Key                       Value
---                       -----
username                  marco
password                  Supers3cr3t!
$ vault token lookup
Key                 Value
---                 -----
accessor            rwpXIHXzbVIMN2TL25Lfssef
creation_time       1629970184
creation_ttl        1m
display_name        jwt-spiffe://dev.localhost/ns/my-app/sa/my-app-backend
entity_id           8904661e-5a9f-3af5-c269-257e8a0a31d0
expire_time         2021-08-26T09:30:44.424072877Z
explicit_max_ttl    0s
id                  s.eOdhqe1hVV0OPS7M0TSeEqjG
issue_time          2021-08-26T09:29:44.424078028Z
meta                map[role:my-role]
num_uses            0
orphan              true
path                auth/jwt/login
policies            [default my-role]
renewable           true
ttl                 13s
type                service
$ vault token renew
Key                  Value
---                  -----
token                s.f1mFvr0TdEuvmfcZT0jBLCc5
token_accessor       vxginlb81XMEIPefLpRz1P24
token_duration       1m
token_renewable      true
token_policies       ["default" "my-role"]
identity_policies    []
policies             ["default" "my-role"]
token_meta_role      my-role
$ vault token lookup
Key                  Value
---                  -----
accessor             vxginlb81XMEIPefLpRz1P24
creation_time        1629970320
creation_ttl         1m
display_name         jwt-spiffe://dev.localhost/ns/my-app/sa/my-app-backend
entity_id            8904661e-5a9f-3af5-c269-257e8a0a31d0
expire_time          2021-08-26T09:33:53.57444787Z
explicit_max_ttl     0s
id                   s.f1mFvr0TdEuvmfcZT0jBLCc5
issue_time           2021-08-26T09:32:00.135787193Z
last_renewal         2021-08-26T09:32:53.574447972Z
last_renewal_time    1629970373
meta                 map[role:my-role]
num_uses             0
orphan               true
path                 auth/jwt/login
policies             [default my-role]
renewable            true
ttl                  56s
type                 service
$ vault write transit/sign/my-key input="$(echo stuff | base64)"
Key            Value
---            -----
key_version    1
signature      vault:v1:MEUCIFAWmHPyLJ6V0mjMgqr5UnV40bkCEUEGqApcYI54VAPIAiEAqyG2VkFc2wpYs/n47mK4vgfTVbXjWJzMM7Fxr/bR7LE=
$ vault write transit/verify/my-key input="$(echo stuff | base64)" signature=vault:v1:MEUCIFAWmHPyLJ6V0mjMgqr5UnV40bkCEUEGqApcYI54VAPIAiEAqyG2VkFc2wpYs/n47mK4vgfTVbXjWJzMM7Fxr/bR7LE=
```

</details>

See the [example](example) directory for an example infrastructure setup on Kubernetes integration the whole eco-system. This includes a Spire, Vault deployment as well utilizing `spiffe-vault` as en example workload.


Spiffe-Vault

SPIRE (the SPIFFE Runtime Environment) is a toolchain of APIs for establishing trust between software systems across a wide variety of hosting platforms.

![SPIRE Logo](/doc/images/spire_logo.png)

[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/3303/badge)](https://bestpractices.coreinfrastructure.org/projects/3303)
[![Build Status](https://github.com/spiffe/spire/actions/workflows/pr_build.yaml/badge.svg)](https://github.com/spiffe/spire/actions/workflows/pr_build.yaml)
[![Go Report Card](https://goreportcard.com/badge/github.com/spiffe/spire)](https://goreportcard.com/report/github.com/spiffe/spire)
[![Production Phase](https://img.shields.io/badge/SPIFFE-Prod-green.svg?logoWidth=18&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHJvbGU9ImltZyIgdmlld0JveD0iMC4xMSAxLjg2IDM1OC4yOCAzNTguMjgiPjxzdHlsZT5zdmcge2VuYWJsZS1iYWNrZ3JvdW5kOm5ldyAwIDAgMzYwIDM2MH08L3N0eWxlPjxzdHlsZT4uc3QyLC5zdDN7ZmlsbC1ydWxlOmV2ZW5vZGQ7Y2xpcC1ydWxlOmV2ZW5vZGQ7ZmlsbDojYmNkOTE4fS5zdDN7ZmlsbDojMDRiZGQ5fTwvc3R5bGU+PGcgaWQ9IkxPR08iPjxwYXRoIGQ9Ik0xMi4xIDguOWgyOC4zYzIuNyAwIDUgMi4yIDUgNXYyOC4zYzAgMi43LTIuMiA1LTUgNUgxMi4xYy0yLjcgMC01LTIuMi01LTVWMTMuOWMuMS0yLjcgMi4zLTUgNS01eiIgY2xhc3M9InN0MiIvPjxwYXRoIGQ9Ik04OC43IDguOWgyNThjMi43IDAgNSAyLjIgNSA1djI4LjNjMCAyLjctMi4yIDUtNSA1aC0yNThjLTIuNyAwLTUtMi4yLTUtNVYxMy45YzAtMi43IDIuMi01IDUtNXoiIGNsYXNzPSJzdDMiLz48cGF0aCBkPSJNMzQ2LjcgODUuNWgtMjguM2MtMi43IDAtNSAyLjItNSA1djI4LjNjMCAyLjggMi4yIDUgNSA1aDI4LjNjMi43IDAgNS0yLjIgNS01VjkwLjVjMC0yLjgtMi4zLTUtNS01eiIgY2xhc3M9InN0MiIvPjxwYXRoIGQ9Ik0xOTMuNiA4NS41SDEyLjFjLTIuNyAwLTUgMi4zLTUgNXYyOC4zYzAgMi43IDIuMiA1IDUgNWgxODEuNWMyLjcgMCA1LTIuMiA1LTVWOTAuNWMwLTIuOC0yLjItNS01LTV6IiBjbGFzcz0ic3QzIi8+PHBhdGggZD0iTTI3MC4yIDg1LjVoLTI4LjNjLTIuNyAwLTUgMi4yLTUgNXYyOC4zYzAgMi44IDIuMiA1IDUgNWgyOC4zYzIuNyAwIDUtMi4yIDUtNVY5MC41Yy0uMS0yLjgtMi4zLTUtNS01eiIgY2xhc3M9InN0MiIvPjxwYXRoIGQ9Ik0yNzAuMiAxNjJIODguN2MtMi43IDAtNSAyLjItNSA1djI4LjNjMCAyLjcgMi4yIDUgNSA1aDE4MS41YzIuNyAwIDUtMi4yIDUtNVYxNjdjLS4xLTIuOC0yLjMtNS01LTV6IiBjbGFzcz0ic3QzIi8+PHBhdGggZD0iTTM0Ni43IDE2MmgtMjguM2MtMi43IDAtNSAyLjItNSA1djI4LjNjMCAyLjggMi4yIDUgNSA1aDI4LjNjMi43IDAgNS0yLjIgNS01VjE2N2MwLTIuOC0yLjMtNS01LTV6bS0zMDYuMyAwSDEyLjFjLTIuNyAwLTUgMi4yLTUgNXYyOC4zYzAgMi44IDIuMiA1IDUgNWgyOC4zYzIuNyAwIDUtMi4yIDUtNVYxNjdjMC0yLjgtMi4yLTUtNS01em0tMjguMyA3Ni41aDI4LjNjMi43IDAgNSAyLjIgNSA1djI4LjNjMCAyLjctMi4yIDUtNSA1SDEyLjFjLTIuNyAwLTUtMi4yLTUtNXYtMjguM2MuMS0yLjcgMi4zLTUgNS01eiIgY2xhc3M9InN0MiIvPjxwYXRoIGQ9Ik0xNjUuMiAyMzguNWgxODEuNWMyLjcgMCA1IDIuMiA1IDV2MjguM2MwIDIuNy0yLjIgNS01IDVIMTY1LjJjLTIuNyAwLTUtMi4yLTUtNXYtMjguM2MwLTIuNyAyLjItNSA1LTV6IiBjbGFzcz0ic3QzIi8+PHBhdGggZD0iTTg4LjcgMjM4LjVIMTE3YzIuNyAwIDUgMi4yIDUgNXYyOC4zYzAgMi43LTIuMiA1LTUgNUg4OC43Yy0yLjcgMC01LTIuMi01LTV2LTI4LjNjMC0yLjcgMi4yLTUgNS01em0yNTggNzYuN2gtMjguM2MtMi43IDAtNSAyLjItNSA1djI4LjNjMCAyLjggMi4yIDUgNSA1aDI4LjNjMi43IDAgNS0yLjIgNS01di0yOC4zYzAtMi44LTIuMy01LTUtNXoiIGNsYXNzPSJzdDIiLz48cGF0aCBkPSJNMjcwLjIgMzE1LjJoLTI1OGMtMi43IDAtNSAyLjItNSA1djI4LjNjMCAyLjcgMi4yIDUgNSA1aDI1OGMyLjcgMCA1LTIuMiA1LTV2LTI4LjNjLS4xLTIuOC0yLjMtNS01LTV6IiBjbGFzcz0ic3QzIi8+PC9nPjwvc3ZnPg==)](https://github.com/spiffe/spiffe/blob/main/MATURITY.md#production)

SPIRE (the [SPIFFE](https://github.com/spiffe/spiffe) Runtime Environment) is a toolchain of APIs for establishing trust between software systems across a wide variety of hosting platforms. SPIRE exposes the [SPIFFE Workload API](https://github.com/spiffe/go-spiffe/blob/main/v2/proto/spiffe/workload/workload.proto), which can attest running software systems and issue [SPIFFE IDs](https://github.com/spiffe/spiffe/blob/main/standards/SPIFFE-ID.md) and [SVID](https://github.com/spiffe/spiffe/blob/main/standards/SPIFFE-ID.md)s to them.  This in turn allows two workloads to establish trust between each other, for example by establishing an mTLS connection or by signing and verifying a JWT token. SPIRE can also enable workloads to securely authenticate to a secret store, a database, or a cloud provider service.

- [Get SPIRE](#get-spire)
- [Learn about SPIRE](#learn-about-spire)
- [Integrate with SPIRE](#integrate-with-spire)
- [Contribute to SPIRE](#contribute-to-spire)
- [Further Reading](#further-reading)
- [Security](#security)

SPIRE is a [graduated](https://www.cncf.io/projects/spire/) project of the [Cloud Native Computing Foundation](https://cncf.io) (CNCF). If you are an organization that wants to help shape the evolution of technologies that are container-packaged, dynamically-scheduled and microservices-oriented, consider joining the CNCF.

## Get SPIRE

- Pre-built releases of SPIRE can be found at [https://github.com/spiffe/spire/releases](https://github.com/spiffe/spire/releases). These releases contain both SPIRE Server and SPIRE Agent binaries.
- Container images are published for [spire-server](https://ghcr.io/spiffe/spire-server), [spire-agent](https://ghcr.io/spiffe/spire-agent), and [oidc-discovery-provider](https://ghcr.io/spiffe/oidc-discovery-provider).
- Alternatively, you can [build SPIRE from source](/CONTRIBUTING.md).

## Learn about SPIRE

- Before trying SPIRE, it's a good idea to learn about its [architecture](https://spiffe.io/spire/) and design goals.
- Once ready to get started, see the [Quickstart Guides](https://spiffe.io/spire/try/) for Kubernetes, Linux, and MacOS.
- There are several examples demonstrating SPIRE usage in the [spire-examples](https://github.com/spiffe/spire-examples) and [spire-tutorials](https://github.com/spiffe/spire-tutorials) repositories.
- Check [ADOPTERS.md](./ADOPTERS.md) for a list of production SPIRE adopters, a view of the ecosystem, and use cases.
- See the [SPIRE Roadmap](/ROADMAP.md) for a list of planned features and enhancements.
- [Join](https://slack.spiffe.io/) the SPIFFE community on Slack. If you have any questions about how SPIRE works, or how to get it up and running, the best places to ask questions are the [SPIFFE Slack channels](https://spiffe.slack.com).
- Download the free book about SPIFFE and SPIRE, "[Solving the Bottom Turtle](https://spiffe.io/book/)."

## Integrate with SPIRE

- See [Extend SPIRE](https://spiffe.io/spire/docs/extending/) to learn about the highly extensible SPIRE plugin framework.
- Officially maintained client libraries for interacting with the [SPIFFE Workload API](https://github.com/spiffe/spiffe/blob/main/standards/SPIFFE_Workload_API.md) are available in [Go](https://github.com/spiffe/go-spiffe/tree/main/v2) and [Java](https://github.com/spiffe/java-spiffe). See [SPIFFE Library Usage Examples](https://spiffe.io/spire/try/spiffe-library-usage-examples/) for a full list of official and community libraries, as well as code samples.
- SPIRE provides an implementation of the [Envoy](https://envoyproxy.io) [Secret Discovery Service](https://www.envoyproxy.io/docs/envoy/latest/configuration/security/secret) (SDS) for use with [Envoy Proxy](https://envoyproxy.io).  SDS can be used to transparently install and rotate TLS certificates and trust bundles in Envoy. See [Using SPIRE with Envoy](https://spiffe.io/spire/docs/envoy/) for more information.

For supported integration versions, see [Supported Integrations](/doc/supported_integrations.md).

## Contribute to SPIRE

The SPIFFE community maintains the SPIRE project. Information on the various SIGs and relevant standards can be found in
<https://github.com/spiffe/spiffe>.

- See [CONTRIBUTING](https://github.com/spiffe/spire/blob/main/CONTRIBUTING.md) to get started.
- Use [GitHub Issues](https://github.com/spiffe/spire/issues) to request features or file bugs.
- See [GOVERNANCE](https://github.com/spiffe/spiffe/blob/main/GOVERNANCE.md) for SPIFFE and SPIRE governance policies.

## Further Reading

- The [Scaling SPIRE guide](/doc/scaling_spire.md) covers design guidelines, recommendations, and deployment models.
- For an explanation of how SPIRE compares to related systems such as secret stores, identity providers, authorization policy engines and service meshes see [comparisons](https://spiffe.io/spire/comparisons/).

## Security

### Security Assessments

A third party security firm ([Cure53](https://cure53.de/)) completed a security audit of SPIFFE and SPIRE in February of 2021. Additionally, the [CNCF Technical Advisory Group for Security](https://github.com/cncf/tag-security) conducted two assessments on SPIFFE and SPIRE in 2018 and 2020. Please find the reports and supporting material, including the threat model exercise results, below.

- [Cure53 Security Audit Report](doc/cure53-report.pdf)
- [SIG-Security SPIFFE/SPIRE Security Assessment: summary](https://github.com/cncf/sig-security/tree/main/assessments/projects/spiffe-spire)
- [SIG-Security SPIFFE/SPIRE Security Assessment: full assessment](https://github.com/cncf/sig-security/blob/main/assessments/projects/spiffe-spire/self-assessment.md)
- [Scrutinizing SPIRE to Sensibly Strengthen SPIFFE Security](https://blog.spiffe.io/scrutinizing-spire-security-9c82ba542019)

### Reporting Security Vulnerabilities

If you've found a vulnerability or a potential vulnerability in SPIRE please let us know at <security@spiffe.io>. We'll send a confirmation email to acknowledge your report, and we'll send an additional email when we've identified the issue positively or negatively.

The Best Go Libraries For Zero Trust - Libraries and tools to implement Zero Trust architectures. (2)

Spiffe-Vault

Spire