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.
Arguments
- login
Login method. Specify a string to be passed along as the
method
argument to$login
. The defaultFALSE
means not to login.TRUE
means to login using a default method specified by the environment variableVAULTR_AUTH_METHOD
- if that variable is not set, an error is thrown. The value ofNULL
is the same asTRUE
but does not throw an error ifVAULTR_AUTH_METHOD
is not set. Supported methods aretoken
,github
,approle
,ldap
, anduserpass
.- ...
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 variableVAULT_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 whenNULL
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 likelyhttps://
but in testinghttp://
might be used)VAULT_CAPATH
: The path to CA certificatesVAULT_TOKEN
: A vault token to use in authentication. Only used for token-based authenticationVAULT_AUTH_GITHUB_TOKEN
: As for the command line client, a github token for authentication using the github authentication backendVAULTR_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
Inherited methods
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)
Method api()
Returns an api client object that can be used to directly interact with the vault server.
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
.
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
.
Method list()
List data in the vault at a given path. This can
be used to list keys, etc (e.g., at /secret
).
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
, anduserpass
.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 thenlogin
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 tologin
at this vault address that useuse_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.
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.
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)
#> ...waiting for Vault to start
#> ...waiting for Vault to start
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")
}
#> Error : Have not authenticated against vault
#> Verifying token