vault_client | R Documentation |
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.
vault_client(
login = FALSE,
...,
addr = NULL,
tls_config = NULL,
namespace = NULL
)
login |
Login method. Specify a string to be passed along as
the |
... |
Additional arguments passed along to the authentication
method indicated by |
addr |
The vault address including protocol and port,
e.g., |
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 |
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 |
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
vaultr::vault_client_object
-> vault_client
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
new()
Create a new vault client. Not typically called
directly, but via the vault_client
method.
vault_client_$new(addr, tls_config, namespace)
addr
The vault address, including protocol and port
tls_config
The TLS config, if used
namespace
The namespace, if used
api()
Returns an api client object that can be used to directly interact with the vault server.
vault_client_$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
.
vault_client_$read(path, field = NULL, metadata = FALSE)
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
.
vault_client_$write(path, data)
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.
delete()
Delete a value from the vault
vault_client_$delete(path)
path
The path to delete
list()
List data in the vault at a given path. This can
be used to list keys, etc (e.g., at /secret
).
vault_client_$list(path, full_names = FALSE)
path
The path to list
full_names
Logical, indicating if full paths (relative to the vault root) should be returned.
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/
login()
Login to the vault. This method is more complicated than most.
vault_client_$login( ..., method = "token", mount = NULL, renew = FALSE, quiet = FALSE, token_only = FALSE, use_cache = TRUE )
...
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.
status()
Return the status of the vault server, including whether it is sealed or not, and the vault server version.
vault_client_$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.
vault_client_$unwrap(token)
token
Specifies the wrapping token ID
wrap_lookup()
Look up properties of a wrapping token.
vault_client_$wrap_lookup(token)
token
Specifies the wrapping token ID to lookup
Rich FitzJohn
# 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")
}
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.