vault

README

Vault Provider

The Vault provider for Secretless can fetch secrets from configured secret engines in HashiCorp Vault. The provider is based on the Vault API client in Go. It reads the secret object from the configured path and returns the value navigated to by the configured fields (or default field otherwise).

Usage Documentation

The Vault provider is configured in the secretless.yml using:

from: vault
get: /path/to/secret/in/vault

Or with explicit fields navigating to the value in the secret returned at path:

from: vault
get: /path/to/secret/in/vault#navigate.to.this.field

The provider will read a secret (object) at a given path and returns the value of field value (by default). By appending #data.fieldName to the path, the provider will instead read the value at the field fieldName in the object data in the secret (object) instead.

Below are some examples showing how to configure the provider for secrets.

Example: API key from KV backends (v1 and v2)

Below is an excerpt of an example configuration for a fictional "Example Service" that requires an API key, e.g. used in a request header. It gets the API key from Vault's KV version 1 backend at path kv/example-service under the secret's value field.

version: 2
services:
  my_example_service:
    connector: generic_http
    listenOn: tcp://0.0.0.0:8080
    credentials:
      apikey:
        from: vault
        get: kv/example-service
        # gets path to API key in Vault, field 'value' holds the API key
    ...

A slightly different configuration explicitly sets the field api-key (instead of the default value) to hold the API key.

version: 2
services:
  my_example_service:
    connector: generic_http
    listenOn: tcp://0.0.0.0:8080
    credentials:
      apikey:
        from: vault
        get: kv/example-service#api-key
        # gets path to API key in Vault, field 'api-key' holds the API key
    ...

If the secret is stored in a KV v2 backend (mounted at secret by default), the configuration must use the use the data segment in the path and the #data.api-key suffix. This is behavior specific to KV v2 in Vault, see Vault API docs.

version: 2
services:
  my_example_service:
    connector: generic_http
    listenOn: tcp://0.0.0.0:8080
    credentials:
      apikey:
        from: vault
        get: secret/data/example-service#data.api-key
        # gets path to API key in Vault stored in the KV v2 secret engine
    ...

Limitations

• Only token-based login to Vault supported at the moment.
• Only secrets that are "read" in Vault are supported at the moment. Backends that require "writes" to obtain the secret (e.g. PKI, dynamic database credentials) are not supported at the moment.
• Backends that have multiple values change simultaneously (e.g. client id and secret, database username and password) are not supported at the moment.
• Limited support for KV v2 secret engine, only latest version of a secret can be retrieved.

Documentation

Index

• Constants
• func ProviderFactory(options plugin_v1.ProviderOptions) (plugin_v1.Provider, error)
• type Provider
  • func (p *Provider) GetName() string
  • func (p *Provider) GetValue(id string) ([]byte, error)
  • func (p *Provider) GetValues(ids ...string) (map[string]plugin_v1.ProviderResponse, error)

Constants

const DefaultField = "value"

DefaultField is the default field name the provider expects to find the secret value.

Functions

func ProviderFactory

func ProviderFactory(options plugin_v1.ProviderOptions) (plugin_v1.Provider, error)

ProviderFactory constructs a Provider. The API client is configured from environment variables. Underlying Vault API client by default uses: - VAULT_ADDR: endpoint of Vault, e.g. http://vault:8200/ - VAULT_TOKEN: token to login to Vault See Vault API docs at https://godoc.org/github.com/hashicorp/vault/api

Types

type Provider

type Provider struct {
	Name   string
	Client *vault.Client
}

Provider provides data values from the Conjur vault.

func (*Provider) GetName

func (p *Provider) GetName() string

GetName returns the name of the provider

func (*Provider) GetValue

func (p *Provider) GetValue(id string) ([]byte, error)

GetValue obtains a value by id. The id should contain the path in Vault to the secret. It may be appended with a hash following the object property path to the secret value; defaults to DefaultField. For example:

• `kv/database/password` returns the value of field `value` in the secret object at given path.
• `kv/database#password` returns the value of field `password` in the secret object at path `kv/database`.
• `secret/data/database#data.value` returns the value of field `value` wrapped in object `data` in secret object at path `secret/data/database`.

Secrets in Vault are stored as (JSON) objects in the shape of map[string]interface{}. Both path to the secret and fields to the value in the secret must follow Vault API client conventions. Please see documentation of Vault for details.

func (*Provider) GetValues

func (p *Provider) GetValues(ids ...string) (map[string]plugin_v1.ProviderResponse, error)

GetValues takes in variable ids and returns their resolved values. This method is needed to the Provider interface