vaultlib

README

vaultlib

Lightweight, simple Go library for Vault secret reading (http API).

Connect to Vault through app role or token.

Reads kv secret values

Features

• Connect to Vault through app role
• Read Vault secret, kv type (v1 or v2 "versioned")
• Automatically renew token
• Execute any HTTP request on Vault (RawRequest)

Config

Configuration can be done through env variables or programmatically through the Config object The following env variables are supported:

VAULT_ADDR            # Vault server URL (default "http://localhost:8200")
VAULT_CACERT          # Path to CA file
VAULT_TOKEN           # Vault Token
VAULT_ROLEID          # Vault app role id
VAULT_SECRETID        # Vault app role secret id
VAULT_MOUNTPOINT      # Vault app role mountpoint (default "approle")
VAULT_CLIENT_TIMEOUT  # Client timeout
VAULT_SKIP_VERIFY     # Do not check SSL

If not set, vaultlib will fallback to safe default values.

vautlib will automatically use the http_proxy environment variable to connect to Vault

Getting Started

For a simple, working example, check the sample folder.

package main

import (
    "fmt"
    "log"
    "os"

    vault "github.com/mch1307/vaultlib"
)

func main() {
    // Config can be set through ENV before invoking NewConfig
    os.Setenv("VAULT_ADDR", "http://localhost:8200")

    // Create a new config. Reads env variables, fallback to default value if needed
    vcConf := vault.NewConfig()

    // Config can also be done programmtically
    vcConf.Address = "http://localhost:8200"

    // set app role credentials (ie after reading from docker secret)
    // vcConf.AppRoleCredentials.RoleID = "myRoleID"
    // vcConf.AppRoleCredentials.SecretID = "mySecretID"
    // if you have set a different mountpoint from "approle" :
    // vcConf.AppRoleCredentials.MountPoint = "myCustomMountPoint"

    // Create new client
    vaultCli, err := vault.NewClient(vcConf)
    if err != nil {
        log.Fatal(err)
    }

    // Get the Vault secret data
    kv, err := vaultCli.GetSecret("my_kv/my_org/my_secret")
    if err != nil {
        fmt.Println(err)
    }
    for k, v := range kv.KV {
        fmt.Printf("secret %v: %v\n", k, v)
    }
}

Documentation

Overview

Package vaultlib is a lightweight Go library for reading Vault KV secrets. Interacts with Vault server using HTTP API only.

First create a new *config object using NewConfig().

Then create you Vault client using NewClient(*config).

See Also

https://github.com/mch1307/vaultlib#vaultlib

Example

// Create a new config. Reads env variables, fallback to default value if needed
vcConf := NewConfig()

// Add the Vault approle secretid after having read it from docker secret
// vcConf.AppRoleCredentials.SecretID

// Create new client
vaultCli, err := NewClient(vcConf)
if err != nil {
	log.Fatal(err)
}

// Get the Vault KV secret from kv_v1/path/my-secret
kvV1, err := vaultCli.GetSecret("kv_v1/path/my-secret")
if err != nil {
	fmt.Println(err)
}
for k, v := range kvV1.KV {
	fmt.Printf("Secret %v: %v\n", k, v)
}
// Get the Vault KVv2 secret kv_v2/path/my-secret
kvV2, err := vaultCli.GetSecret("kv_v2/path/my-secret")
if err != nil {
	fmt.Println(err)
}
for k, v := range kvV2.KV {
	fmt.Printf("Secret %v: %v\n", k, v)
}
jsonSecret, err := vaultCli.GetSecret("kv_v2/path/json-secret")
if err != nil {
	fmt.Println(err)
}
fmt.Println(fmt.Sprintf("%v", jsonSecret.JSONSecret))

Index

• type AppRoleCredentials
• type Client
  • func NewClient(c *Config) (*Client, error)
  • func (c *Client) GetSecret(path string) (secret Secret, err error)
  • func (c *Client) GetStatus() string
  • func (c *Client) GetTokenInfo() *VaultTokenInfo
  • func (c *Client) IsAuthenticated() bool
  • func (c *Client) RawRequest(method, path string, payload interface{}) (result json.RawMessage, err error)
• type Config
  • func NewConfig() *Config
• type Secret
• type VaultTokenInfo

Examples

• Package
• Client.IsAuthenticated
• NewClient
• NewConfig

Types

type AppRoleCredentials

type AppRoleCredentials struct {
	RoleID     string `json:"role_id"`
	SecretID   string `json:"secret_id"`
	MountPoint string `json:"-"`
}

AppRoleCredentials holds the app role secret and role ids

type Client

type Client struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

Client holds the vault client

func NewClient

func NewClient(c *Config) (*Client, error)

NewClient returns a new client based on the provided config

Example

myConfig := NewConfig()
myVaultClient, err := NewClient(myConfig)
if err != nil {
	fmt.Println(err)
}
fmt.Println(myVaultClient.address)

func (*Client) GetSecret

func (c *Client) GetSecret(path string) (secret Secret, err error)

GetSecret returns the Vault secret object

KV: map[string]string if the secret is a KV

JSONSecret: json.RawMessage if the secret is a json

func (*Client) GetStatus

func (c *Client) GetStatus() string

GetStatus return the last action status/log

func (*Client) GetTokenInfo

func (c *Client) GetTokenInfo() *VaultTokenInfo

GetTokenInfo returns the current token information

func (*Client) IsAuthenticated

func (c *Client) IsAuthenticated() bool

IsAuthenticated returns bool if last call to vault was ok

Example

myConfig := NewConfig()
myVaultClient, err := NewClient(myConfig)
if err != nil {
	fmt.Println(err)
}
if myVaultClient.IsAuthenticated() {
	fmt.Println("myVaultClient's connection is ok")
}

func (*Client) RawRequest

func (c *Client) RawRequest(method, path string, payload interface{}) (result json.RawMessage, err error)

RawRequest create and execute http request against Vault HTTP API for client. Use the client's token for authentication.

Specify http method, Vault path (ie /v1/auth/token/lookup) and optional json payload. Return the Vault JSON response .

type Config

type Config struct {
	Address            string
	MaxRetries         int
	Timeout            time.Duration
	CACert             string
	InsecureSSL        bool
	AppRoleCredentials *AppRoleCredentials
	Token              string
	Namespace          string
}

Config holds the vault client config

func NewConfig

func NewConfig() *Config

NewConfig returns a new configuration based on env vars or default value.

Reads ENV:

	VAULT_ADDR            Vault server URL (default http://localhost:8200)
	VAULT_ROLEID          Vault app role id
	VAULT_SECRETID        Vault app role secret id
	VAULT_MOUNTPOINT      Vault app role mountpoint (default "approle")
	VAULT_TOKEN           Vault Token (in case approle is not used)
	VAULT_CACERT          Path to CA pem file
	VAULT_SKIP_VERIFY     Do not check SSL
	VAULT_CLIENT_TIMEOUT  Client timeout
 VAULT_NAMESPACE		  Vault Namespace

Modify the returned config object to adjust your configuration.

Example

myConfig := NewConfig()
myConfig.Address = "http://localhost:8200"

type Secret

type Secret struct {
	KV         map[string]string
	JSONSecret json.RawMessage
}

Secret holds the secret.

KV contains data in case of KV secret.

JSONSecret contains data in case of JSON raw secret.

type VaultTokenInfo

type VaultTokenInfo struct {
	Accessor       string      `json:"accessor"`
	CreationTime   int         `json:"creation_time"`
	CreationTTL    int         `json:"creation_ttl"`
	DisplayName    string      `json:"display_name"`
	EntityID       string      `json:"entity_id"`
	ExpireTime     interface{} `json:"expire_time"`
	ExplicitMaxTTL int         `json:"explicit_max_ttl"`
	ID             string      `json:"id"`
	IssueTime      time.Time   `json:"issue_time"`
	Meta           interface{} `json:"meta"`
	NumUses        int         `json:"num_uses"`
	Orphan         bool        `json:"orphan"`
	Path           string      `json:"path"`
	Policies       []string    `json:"policies"`
	Renewable      bool        `json:"renewable"`
	TTL            int         `json:"ttl"`
	Type           string      `json:"type"`
}

VaultTokenInfo holds the Vault token information