vault_client: Make a vault client

In vaultr: Vault Client for Secrets and Sensitive Data

Make a vault client

Description

Make a vault client. This must be done before accessing the vault. The default values for arguments are controlled by environment variables (see Details) and values provided as arguments override these defaults.

Usage

vault_client(
  login = FALSE,
  ...,
  addr = NULL,
  tls_config = NULL,
  namespace = NULL
)

Arguments

login	Login method. Specify a string to be passed along as the method argument to ⁠$login⁠. The default FALSE means not to login. TRUE means to login using a default method specified by the environment variable VAULTR_AUTH_METHOD - if that variable is not set, an error is thrown. The value of NULL is the same as TRUE but does not throw an error if VAULTR_AUTH_METHOD is not set. Supported methods are token, github, approle, ldap, and userpass.
...	Additional arguments passed along to the authentication method indicated by login, if used.
addr	The vault address including protocol and port, e.g., ⁠https://vault.example.com:8200⁠. If not given, the default is the environment variable VAULT_ADDR, which is the same as used by vault's command line client.
tls_config	TLS (https) configuration. For most uses this can be left blank. However, if your vault server uses a self-signed certificate you will need to provide this. Defaults to the environment variable VAULT_CAPATH, which is the same as vault's command line client.
namespace	A vault namespace, when using enterprise vault. If given, then this must be a string, and your vault must support namespaces, which is an enterprise feature. If the environment variable VAULT_NAMESPACE is set, we use that namespace when NULL is provided as an argument (this is the same variable as used by vault's command line client).

Environment variables

The creation of a client is affected by a number of environment variables, following the main vault command line client.

• VAULT_ADDR: The url of the vault server. Must include a protocol (most likely ⁠https://⁠ but in testing ⁠http://⁠ might be used)

• VAULT_CAPATH: The path to CA certificates

• VAULT_TOKEN: A vault token to use in authentication. Only used for token-based authentication

• VAULT_AUTH_GITHUB_TOKEN: As for the command line client, a github token for authentication using the github authentication backend

• VAULTR_AUTH_METHOD: The method to use for authentication

Super class

vaultr::vault_client_object -> vault_client

Public fields

auth

Authentication backends: vault_client_auth

audit

Audit methods: vault_client_audit

cubbyhole

The vault cubbyhole key-value store: vault_client_cubbyhole

operator

Operator methods: vault_client_operator

policy

Policy methods: vault_client_policy

secrets

Secret backends: vault_client_secrets

token

Token methods: vault_client_token

tools

Vault tools: vault_client_tools

Methods

Public methods

• vault_client_$new()

• vault_client_$api()

• vault_client_$read()

• vault_client_$write()

• vault_client_$delete()

• vault_client_$list()

• vault_client_$login()

• vault_client_$status()

• vault_client_$unwrap()

• vault_client_$wrap_lookup()

Inherited methods

• vaultr::vault_client_object$format()
• vaultr::vault_client_object$help()

---

Method new()

Create a new vault client. Not typically called directly, but via the vault_client method.

Usage

vault_client_$new(addr, tls_config, namespace)

Arguments

addr

The vault address, including protocol and port

tls_config

The TLS config, if used

namespace

The namespace, if used

---

Method api()

Returns an api client object that can be used to directly interact with the vault server.

Usage

vault_client_$api()

---

Method read()

Read a value from the vault. This can be used to read any value that you have permission to read, and can also be used as an interface to a version 1 key-value store (see vault_client_kv1. Similar to the vault CLI command ⁠vault read⁠.

Usage

vault_client_$read(path, field = NULL, metadata = FALSE)

Arguments

path

Path for the secret to read, such as ⁠/secret/mysecret⁠

field

Optional field to read from the secret. Each secret is stored as a key/value set (represented in R as a named list) and this is equivalent to using ⁠[[field]]⁠ on the return value. The default, NULL, returns the full set of values.

metadata

Logical, indicating if we should return metadata for this secret (lease information etc) as an attribute along with the values itself. Ignored if field is specified.

---

Method write()

Write data into the vault. This can be used to write any value that you have permission to write, and can also be used as an interface to a version 1 key-value store (see vault_client_kv1. Similar to the vault CLI command ⁠vault write⁠.

Usage

vault_client_$write(path, data)

Arguments

path

Path for the secret to write, such as ⁠/secret/mysecret⁠

data

A named list of values to write into the vault at this path. This replaces any existing values.

---

Method delete()

Delete a value from the vault

Usage

vault_client_$delete(path)

Arguments

path

The path to delete

---

Method list()

List data in the vault at a given path. This can be used to list keys, etc (e.g., at ⁠/secret⁠).

Usage

vault_client_$list(path, full_names = FALSE)

Arguments

path

The path to list

full_names

Logical, indicating if full paths (relative to the vault root) should be returned.

Returns

A character vector (of zero length if no keys are found). Paths that are "directories" (i.e., that contain keys and could themselves be listed) will be returned with a trailing forward slash, e.g. ⁠path/⁠

---

Method login()

Login to the vault. This method is more complicated than most.

Usage

vault_client_$login(
  ...,
  method = "token",
  mount = NULL,
  renew = FALSE,
  quiet = FALSE,
  token_only = FALSE,
  use_cache = TRUE
)

Arguments

...

Additional named parameters passed through to the underlying method

method

Authentication method to use, as a string. Supported values include token (the default), github, approle, ldap, and userpass.

mount

The mount path for the authentication backend, if it has been mounted in a nonstandard location. If not given, then it is assumed that the backend was mounted at a path corresponding to the method name.

renew

Login, even if we appear to hold a valid token. If FALSE and we have a token then login does nothing.

quiet

Suppress some informational messages

token_only

Logical, indicating that we do not want to actually log in, but instead just generate a token and return that. IF given then renew is ignored and we always generate a new token.

use_cache

Logical, indicating if we should look in the session cache for a token for this client. If this is TRUE then when we log in we save a copy of the token for this session and any subsequent calls to login at this vault address that use use_cache = TRUE will be able to use this token. Using cached tokens will make using some authentication backends that require authentication with external resources (e.g., github) much faster.

---

Method status()

Return the status of the vault server, including whether it is sealed or not, and the vault server version.

Usage

vault_client_$status()

---

Method unwrap()

Returns the original response inside the given wrapping token. The vault endpoints used by this method perform validation checks on the token, returns the original value on the wire rather than a JSON string representation of it, and ensures that the response is properly audit-logged.

Usage

vault_client_$unwrap(token)

Arguments

token

Specifies the wrapping token ID

---

Method wrap_lookup()

Look up properties of a wrapping token.

Usage

vault_client_$wrap_lookup(token)

Arguments

token

Specifies the wrapping token ID to lookup

Author(s)

Rich FitzJohn

Examples

# We work with a test vault server here (see ?vault_test_server) for
# details.  To use it, you must have a vault binary installed on your
# system.  These examples will not affect any real running vault
# instance that you can connect to.
server <- vaultr::vault_test_server(if_disabled = message)

if (!is.null(server)) {
  # Create a vault_client object by providing the address of the vault
  # server.
  client <- vaultr::vault_client(addr = server$addr)

  # The client has many methods, grouped into a structure:
  client

  # For example, token related commands:
  client$token

  # The client is not authenticated by default:
  try(client$list("/secret"))

  # A few methods are unauthenticated and can still be run
  client$status()

  # Login to the vault, using the token that we know from the server -
  # ordinarily you would use a login approach suitable for your needs
  # (see the vault documentation).
  token <- server$token
  client$login(method = "token", token = token)

  # The vault contains no secrets at present
  client$list("/secret")

  # Secrets can contain any (reasonable) number of key-value pairs,
  # passed in as a list
  client$write("/secret/users/alice", list(password = "s3cret!"))

  # The whole list can be read out
  client$read("/secret/users/alice")
  # ...or just a field
  client$read("/secret/users/alice", "password")

  # Reading non-existant values returns NULL, not an error
  client$read("/secret/users/bob")

  client$delete("/secret/users/alice")
}

vaultr documentation built on Nov. 9, 2023, 5:07 p.m.