@spec auth(t(), map()) :: {:ok, t()} | {:error, [term()]}

Authenticate against the configured auth backend.

examples

Examples

A successful authentication returns a client containing a valid token, as well as the expiration time for the token. Perform this operation before reading or writing secrets.

Errors from vault are returned as a list of strings.

Uses pre-configured credentials if provided. Passed in credentials will override existing credentials.

{:ok, vault} = Vault.set_credentials(vault, %{username: "UserN4me", password: "P@55w0rd"})

{:error, ["Missing Credentials, username and password are required"]} =
  Vault.set_credentials(vault, %{username: "whoops"})

@spec delete(t(), String.t(), keyword()) :: {:ok, map()} | {:error, term()}

Delete a secret from the configured secret engine.

examples

Examples

Returns the response from vault, which is typically an empty map. See Secret Engine Adapter options for further configuration.

{:ok, %{} }} = Vault.delete(vault,"secret/path/to/write")
{:error, ["Key not found"]} = Vault.list(vault,"secret/bad/path/")

@spec list(t(), String.t(), keyword()) :: {:ok, map()} | {:error, term()}

List secret keys available at a certain path.

examples

Examples

Path should end with a trailing slash. Provided adapters returns the values on the data key from vault, if present. See Secret Engine adapter details for additional configuration, such as returning the full response.

Errors from vault are returned as a list of strings.

{:ok, %{ "keys" => ["some/", "paths", "returned"] }} = Vault.list(vault,"secret/path/to/write")
{:error, ["Unauthorized"]} = Vault.list(vault,"secret/bad/path/")

@spec new(options()) :: t()

Create a new client. Optionally provide a keyword list or map of options for configuration.

examples

Examples

Return a default Vault client:

vault = Vault.new()

Return a fully initialized Vault Client:

vault = Vault.new(%{
  http: Vault.HTTP.Tesla,
  host: "my-vault-instance.example.com",
  auth: Vault.Auth.JWT,
  auth_path: 'jwt',
  engine: Vault.Engine.Generic,
  token: "abc123",
  token_expires_at: NaiveDateTime.utc_now() |> NaiveDateTime.add(30, :second),
  credentials: %{role_id: "dev-role", jwt: "averylongstringoflettersandnumbers..."}
})

options

Options

The following options can be provided as part of the :vault application config, or as a Keyword List or Map of options. Runtime configuration will always take precedence.

• :auth - Module for your Auth adapter.

• :auth_path - Path to use for your auth adapter. Provided adapters have their own default paths. Check your adapter for details.

• :engine Module for your Secret Engine adapter. Defaults to Vault.Engine.Generic.

• :host - host of your vault instance. Should contain the port, if needed. Should not contain a trailing slash. Defaults to System.get_env("VAULT_ADDR").

• :http - Module for your http adapter. Defaults to Vault.HTTP.Tesla when :tesla is present.

• :http_options - A keyword list of options to your HTTP adapter.

• :token - A vault token.

• :token_expires_at A NaiveDateTime instance that represents when the token expires, in utc.

• :credentials - The credentials to use when authenticating with your Auth adapter.

@spec read(t(), String.t(), keyword()) :: {:ok, map()} | {:error, term()}

Read a secret from the configured secret engine.

examples

Examples

Provided adapters return the values on the data key from vault, if present. See Secret Engine adapter details for additional configuration, such as returning the full response.

Errors from vault are returned as a list of strings.

{:ok, %{ password: "value" }} = Vault.write(vault,"secret/path/to/read")
{:error, ["Unauthorized"]} = Vault.read(vault,"secret/bad/path")

@spec request(t(), method(), String.t(), keyword()) ::
  {:ok, term()} | {:error, list()}

Make an HTTP request against your Vault instance, with the current Vault token.

examples

Examples

This library doesn't cover every vault API, but this can help fill some of the gaps, and removing some boilerplate around token management, and JSON parsing.

It can also be handy for renewing dynamic secrets, if you're using the AWS Secret backend.

Requests can take the following options a Keyword List.

options

Options:

• :query_params - a keyword list of query params for the request. Do not include query params on the path.

• :body - Map. The body for the request

• :headers - Keyword list. The headers for the request

• :version - String. The vault api version - defaults to "v1"

general-example

General Example

Here's a generic example for making a request:

vault = Vault.new(
  http: Vault.HTTP.Tesla,
  host: "http://localhost",
  token: "token"
  token_expires_in: NaiveDateTime.utc_now()
)

Vault.request(vault, :post, "path/to/call", [ body: %{ "foo" => "bar"}])
# POST to http://localhost/v1/path/to/call
# with headers: {"X-Vault-Token", "token"}
# and a JSON payload of: "{ 'foo': 'bar'}"

aws-lease-renewal

AWS lease renewal

A quick example of renewing a lease.

vault = Vault.new(
  http: Vault.HTTP.Tesla,
  host: "http://localhost",
  token: "token"
  token_expires_in: NaiveDateTime.utc_now()
)

body = %{lease_id: lease, increment: increment}
{:ok, response} = Vault.request(vault, request(:put, "sys/leases/renew", [body: body])

@spec set_auth(t(), auth()) :: t()

Set the backend to use for authenticating the client.

examples

Examples

The auth backend should be a module that meets the Vault.Auth.Adapter behaviour.

vault = Vault.set_auth(vault, Vault.Auth.Approle)

@spec set_auth_path(t(), auth_path()) :: t()

Set the path used when logging in with your auth adapter.

examples

Examples

Auth backends can be mounted at any path on /auth/. If left unset, the auth adapter may provide a default, eg userpass. See your Auth adapter for details.

vault = Vault.set_auth_path(vault, "auth-path")

@spec set_credentials(t(), map()) :: t()

Sets the login credentials for this client.

examples

Examples

vault = Vault.set_credentials(vault, %{username: "UserN4me", password: "P@55w0rd"})

@spec set_engine(t(), engine()) :: t()

Set the secret engine for the client.

examples

Examples

The secret engine should be a module that meets the Vault.Engine.Adapter behaviour.

vault = Vault.set_engine(vault, Vault.Engine.KVV2)

@spec set_host(t(), host()) :: t()

Set the host of your vault instance.

examples

Examples

The host can be fetched from anywhere, as long as it's a string.

vault = Vault.set_host(vault, System.get_env("VAULT_ADDR"))

The port should be provided if needed, along with the protocol.

vault = Vault.set_host(vault, "https://my-vault.host.com:12345")

@spec set_http(t(), http()) :: t()

Set the http module used to make API calls.

examples

Examples

Should be a module that meets the Vault.HTTP.Adapter behaviour.

vault = Vault.set_http(vault, Vault.HTTP.Tesla)

@spec token_expired?(t()) :: true | false

Check if the current token is still valid.

examples

Examples

Returns true if the current time is later than the expiration date, otherwise false.

true = Vault.token_expired?(vault)

Get a NaiveDateTime struct, in UTC, for when the current token will expire.

examples

Examples

Expiration time is generated from the current time on the current server.

~N[2018-11-25 16:30:30.177731] = Vault.token_expires_at(vault)

@spec write(t(), String.t(), term(), keyword()) :: {:ok, map()} | {:error, term()}

Write a secret to the configured secret engine.

examples

Examples

Provided adapters returns the values on the data key from vault, if present. See Secret Engine adapter details for additional configuration, such as returning the full response.

Errors from vault are returned as a list of strings.

{:ok, %{ version: 1 }} = Vault.write(vault,"secret/path/to/write", %{ secret: "value"})
{:error, ["Unauthorized"]} = Vault.write(vault,"secret/bad/path", %{ secret: "value"})