vault_client: 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)

Arguments

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 and userpass.

...

Additional arguments passed along to the authentication method indicated by login, if used.

addr

The value 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.

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

Methods

api

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

api()

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:

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.

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:

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.

list

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

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.

Value: 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/

delete

Delete a value from the vault Usage:

delete(path)

Arguments:

path: The path to delete

login

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 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.

status

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

status()

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:

unwrap(token)

Arguments:

token: Specifies the wrapping token ID

wrap_lookup

Look up properties of a wrapping token. Usage:

wrap_lookup(token)

Arguments:

token: Specifies the wrapping token ID to lookup

Examples

Run this code

# NOT RUN {

# 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")
}
# }

Run the code above in your browser using DataLab