``` {r include = FALSE} srv <- vaultr::vault_test_server() srv$export() local({ cl <- srv$client() cl$write("/secret/database/admin", list(value = "s3cret")) cl$write("/secret/database/readonly", list(value = "passw0rd")) cl$policy$write("basic", 'path "secret/*" {\n policy = "read"}') cl$auth$enable("userpass") cl$auth$userpass$write("alice", "p4ssw0rd", "basic") })
## Connecting to vault 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 vault * `VAULT_TOKEN`: the token to authenticate to vault with * `VAULTR_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: ``` {r } Sys.getenv(c("VAULT_ADDR", "VAULT_TOKEN", "VAULTR_AUTH_METHOD"))
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
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
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") vault$list("secret/database")
values that terminate in /
are "directories".
Read secrets with $read
:
vault$read("secret/database/readonly")
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")
Delete secrets with $delete
:
vault$delete("secret/database/readonly")
After which the data is no longer available:
vault$read("secret/database/readonly")
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") cl$read("secret/webserver")
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.