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:
Sys.getenv(c("VAULT_ADDR", "VAULT_TOKEN", "VAULTR_AUTH_METHOD"))
## 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:
vault <- vaultr::vault_client(login = TRUE, quiet = TRUE)
This creates an R6
object with methods for interacting with vault:
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
## <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
:
vault$list("secret")
## [1] "database/"
vault$list("secret/database")
## [1] "admin" "readonly"
values that terminate in /
are "directories".
Read secrets with $read
:
vault$read("secret/database/readonly")
## $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:
vault$read("secret/database/readonly", field = "value")
## [1] "passw0rd"
Delete secrets with $delete
:
vault$delete("secret/database/readonly")
After which the data is no longer available:
vault$read("secret/database/readonly")
## NULL
Write new secrets with $write
:
vault$write("secret/webserver", list(password = "horsestaple"))
(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
.
cl <- vaultr::vault_client(login = "userpass", username = "alice", password = "p4ssw0rd")
## ok, duration: 2764800 s (~32d)
cl$read("secret/webserver")
## $password ## [1] "horsestaple"
This is obviously insecure! vaultr
can use
getPass
to securely
prompt for a password:
cl <- vaultr::vault_client(login = "userpass", username = "alice") ## Password for 'alice': ******** ## ok, duration: 2764800 s (~32d)
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:
cl <- vaultr::vault_client(login = "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.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.