Description
Highly configurable library for HashiCorp's Vault - handles authentication
for multiple backends, and reading, writing, listing, and deleting secrets
for a variety of engines.
When possible, it tries to emulate the CLI, with read, write, list and
delete and auth methods. An additional request method is provided when you need
further flexibility with the API.
libvault alternatives and similar packages
Based on the "Third Party APIs" category.
Alternatively, view libvault alternatives based on common mentions on social networks and blogs.
-
-
-
-
-
-
MongoosePush
MongoosePush is a simple Elixir RESTful service allowing to send push notification via FCM and/or APNS. -
-
-
-
-
-
-
cashier
Cashier is an Elixir library that aims to be an easy to use payment gateway, whilst offering the fault tolerance and scalability benefits of being built on top of Erlang/OTP -
-
WorkOS - The modern identity platform for B2B SaaS
Do you think we are missing an alternative of libvault or a related project?
README
libvault
Highly configurable library for HashiCorp's Vault - handles authentication for multiple backends, and reading, writing, listing, and deleting secrets for a variety of engines.
When possible, it tries to emulate the CLI, with read, write, list and
delete and auth methods. An additional request method is provided when you need
further flexibility with the API.
API Preview
{:ok, vault } =
Vault.new([
engine: Vault.Engine.KVV2,
auth: Vault.Auth.UserPass
])
|> Vault.auth(%{username: "username", password: "password"})
{:ok, db_pass} = Vault.read(vault, "secret/path/to/password")
{:ok, %{"version" => 1 }} = Vault.write(vault, "secret/path/to/creds", %{secret: "secrets!"})
Configuration / Adapters
Hashicorp's Vault is highly configurable. Rather than cover every possible option, this library strives to be flexible and adaptable. Auth backends, Secret Engines, and HTTP clients are all replaceable, and each behaviour asks for a minimal contract.
HTTP Adapters
The following HTTP Adapters are provided:
Be sure to add applications and dependencies to your mix file as needed.
JSON Adapters
Most JSON libraries provide the same methods, so no default adapter is needed.
You can use Jason, JSX, Poison, or whatever encoder you want.
Defaults to Jason or Poison if present.
See Vault.JSON.Adapter for the full behaviour interface.
Auth Adapters
Adapters have been provided for the following auth backends:
- AppRole with
Vault.Auth.Approle - Azure with
Vault.Auth.Azure - GitHub with
Vault.Auth.Github - GoogleCloud with with
Vault.Auth.GoogleCloud - JWT with
Vault.Auth.JWT - Kubernetes with
Vault.Auth.Kubernetes - LDAP with
Vault.Auth.LDAP - UserPass with
Vault.Auth.UserPass - Token with
Vault.Auth.Token
In addition to the above, a generic backend is also provided (Vault.Auth.Generic).
If support for auth provider is missing, you can still get up and running
quickly, without writing a new adapter.
Secret Engine Adapters
Most of Vault's Secret Engines use a replacable API. The Vault.Engine.Generic
adapter should handle most use cases for secret fetching.
Vault's KV version 2 broke away from the standard REST convention. So KV has been given its own adapter:
Additional request methods
The core library only handles the basics around secret fetching. If you need to
access additional API endpoints, this library also provides a Vault.request
method. This should allow you to tap into the complete vault REST API, while still
benefiting from token control, JSON parsing, and other HTTP client nicities.
Installation and Usage
Installation
Ensure that any adapter dependencies have been included as part of your application's dependencies:
def deps do
[
{:libvault, "~> 0.2.0"},
# tesla, required for Vault.HTTP.Tesla
{:tesla, "~> 1.3.0"},
# pick your HTTP client - Mint, iBrowse or hackney
{:mint, "~> 0.4.0"},
{:castore, "~> 0.1.0"},
# Pick your json parser - Jason or Poison
{:jason, ">= 1.0.0"}
]
end
Usage
vault =
Vault.new([
engine: Vault.Engine.KVV2,
auth: Vault.Auth.UserPass,
json: Jason,
credentials: %{username: "username", password: "password"}
])
|> Vault.auth()
{:ok, db_pass} = Vault.read(vault, "secret/path/to/password")
{:ok, %{"version" => 1 }} = Vault.write(vault, "secret/path/to/creds", %{secret: "secrets!"})
You can configure the vault client up front, or change configuration on the fly.
vault =
Vault.new()
|> Vault.set_auth(Vault.Auth.Approle)
|> Vault.set_engine(Vault.Engine.Generic)
|> Vault.auth(%{role_id: "role_id", secret_id: "secret_id"})
{:ok, db_pass} = Vault.read(vault, "secret/path/to/password")
vault = Vault.set_engine(Vault.Engine.KVV2) // switch to versioned secrets
{:ok, db_pass} = Vault.write(vault, "kv/path/to/password", %{ password: "db_pass" })
See the full Vault client for additional methods.
Testing Locally
When possible, tests run against a local vault instance. Otherwise, tests run against the Vault Spec, using bypass to test to confirm the success case, and follows vault patterns for failure.
Install the Vault Go CLI https://www.vaultproject.io/downloads.html
In the current directory, set up a local dev server with
sh scripts/setup-local-vaultVault (at this time) can't be run in the background without a docker instance. For now, set up the local secret engine paths with
sh scripts/setup-engines.sh
Documentation can be generated with ExDoc and published on HexDocs. Once published, the docs can be found at https://hexdocs.pm/libvault.