SPIRE Vault Authentication Plugin

SPIRE Vault Authentication Plugin is an authentication plugin for Hashicorp Vault which allows logging into Vault using a SPIRE provided SVID.

Menu

• Rationale
• Quick start
• Building
• Installation
• Contributions
• License
• Code of Conduct
• Security Vulnerability Reporting

Rationale

This 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

$> vault write auth/spire/login jwt="<jwt svid>"
$> vault write auth/spire/login -client-cert=svid.0.pem  -client-key=svid.0.key" <-- TLS connection using X509-SVID

where the SVID contains a valid SpiffeID which is used to determine which policies to apply during the Vault session.

Currently 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 for a discussion on accepting X509-SVIDs.

During 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, 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.

The 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.

Trust Sources

A 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.

File Trust Source

When 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.

{
  "trustsource": {
    "file": {
      "domains": {
        "spiffe://some.domain.com": ["/path/to/ca/for/domain.crt", "/path/to/secondary/ca/for/domain.crt"],
        "spiffe://some.otherdomain.com": ["/path/to/ca/for/otherdomain.crt"]
      }
    }
  }
}

Each 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.

SPIRE Trust Source

This is still under development and some details are unknown at this time

When 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

{
  "trustsource": {
    "spire": ...unknown at the moment...
  }
}

Current ideas for this trust source include

1. Support connecting to multiple SPIRE instances (agents or servers) to allow for broad authentication, particularly where different systems are using the same Vault instance.
2. 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.

Quick Start

Building

The plugin can be built using standard go commands or simply by using the provided Makefile.

$> make build
GOOS=linux GOARCH=amd64 go build -o vault-auth-spire cmd/plugin/vault-auth-spire.go

Installation

The plugin is installed and registered just like any other Vault plugin. 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.

$> vault write sys/plugins/catalog/auth/spire \
    sha_256="$(shasum -a 256 '/path/to/plugin/vault-auth-spire' | cut -d' ' -f1)" \
    command="vault-auth-spire" \
    args="--settings-file=/path/to/settings/vault-auth-spire-settings.json"

Before usage all plugins need to be enabled

$> vault auth enable \
    -path="spire" \
    -plugin-name="spire" plugin

Contributions

We ❤️ contributions.

Have 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?

We welcome issue reports here; be sure to choose the proper issue template for your issue, so that we can be sure you're providing the necessary information.

Before sending a Pull Request, please make sure you read our Contribution Guidelines.

License

Please read the LICENSE file.

Code of Conduct

This project has adopted a Code of Conduct. If you have any concerns about the Code, or behavior which you have experienced in the project, please contact us at [email protected].

Security Vulnerability Reporting

If you believe you have identified a security vulnerability in this project, please send email to the project team at [email protected], detailing the suspected issue and any methods you've found to reproduce it.

Please do NOT open an issue in the GitHub repository, as we'd prefer to keep vulnerability reports private until we've had an opportunity to review and address them.