The first part of the vignette assumes that vault is set up; later we show how to control login behaviour and configure vault itself. Access of vault requires several environment variables configured, in particular:
VAULT_ADDR
: the address of vaultVAULT_TOKEN
: the token to authenticate to vault
withVAULTR_AUTH_METHOD
: the method to use to authenticate
with (login to) vault.(environment variables starting with VAULT_
are shared
with the vault cli, variables starting VAULTR_
are specific
to this package).
in this vignette, these are already configured:
## VAULT_ADDR VAULT_TOKEN
## "http://127.0.0.1:18200" "1cd28503-0d1d-cb1d-80ce-30d3bfeb2e31"
## VAULTR_AUTH_METHOD
## "token"
To access vault, first create a client:
This creates an R6
object
with methods for interacting with vault:
## <vault: client>
## Command groups:
## audit: Interact with vault's audit devices
## auth: administer vault's authentication methods
## operator: Administration commands for vault operators
## policy: Interact with policies
## secrets: Interact with secret engines
## token: Interact and configure vault's token support
## tools: General tools provided by vault
## Commands:
## api()
## delete(path)
## help()
## list(path, full_names = FALSE)
## login(..., method = "token", mount = NULL, renew = FALSE,
## quiet = FALSE, token_only = FALSE, use_cache = TRUE)
## read(path, field = NULL, metadata = FALSE)
## status()
## unwrap(token)
## wrap_lookup(token)
## write(path, data)
Because there are many methods, these are organised
hierarchically, similar to the vault cli client. For example
vault$auth
contains commands for interacting with
authentication backends (and itself contains further command
groups):
## <vault: auth>
## Command groups:
## approle: Interact and configure vault's AppRole support
## github: Interact and configure vault's github support
## ldap: Interact and configure vault's LDAP support
## token: Interact and configure vault's token support
## userpass: Interact and configure vault's userpass support
## Commands:
## backends()
## disable(path)
## enable(type, description = NULL, local = FALSE, path = NULL)
## help()
## list(detailed = FALSE)
It is anticipated that the vast majority of vaultr
usage
will be interacting with vault’s key-value stores - this is is done with
the $read
, $write
, $list
and
$delete
methods of the base vault client object. By
default, a vault server will have a version-1
key value store mounted at /secret
.
List secrets with $list
:
## [1] "database/"
## [1] "admin" "readonly"
values that terminate in /
are “directories”.
Read secrets with $read
:
## $value
## [1] "passw0rd"
secrets are returned as a list
, because multiple secrets
may be stored at a path. To access a single field, use the
field
argument:
## [1] "passw0rd"
Delete secrets with $delete
:
After which the data is no longer available:
## NULL
Write new secrets with $write
:
(be aware that this may well write the secret into your R history
file .Rhistory
- to be more secure you may want to read
these in from environment variables and use Sys.getenv()
to
read them into R).
Using the token
approach for authentication requires
that you have already authenticated with vault to get a token. It is
usually more convenient to instead use some other method. Vault itself
supports many
authentication methods but vaultr
currently supports
only GitHub and username/password at this point.
This document should not be used as a reference point for configuring vault in any situation other than testing. Please refer to the vault documentation first.
If you want to configure vault from R rather than the command line client, you will find a very close mapping between argument names. We will here assume that the methods are already configured by your vault administrator and show how to interact with them.
userpass
)Assume vault has been configured to support userpass
authentication and that a user alice
exists with password
p4ssw0rd
.
## ok, duration: 2764800 s (~32d)
## $password
## [1] "horsestaple"
This is obviously insecure! vaultr
can use getPass
to securely prompt for a password:
github
)Assuming that vault has been configured to support GitHub,
and that the environment variable VAULT_AUTH_GITHUB_TOKEN
contains a personal access token for a team that has been configured to
have vault access, then you can log in with github:
See ?vault_client_auth_github
for details.
ldap
)If your organisation uses LDAP and has configured vault to enable that at the server level, you can login using that by passing login = “ldap” along with your username:
cl <- vaultr::vault_client(login = "ldap", username = "alice")
## Password for 'alice': ********
## ok, duration: 2764800 s (~32d)
This will authenticate with the LDAP server, and generate an
appropriate token. See ?vault_client_auth_ldap
for
details.