vaultr

Rich FitzJohn

2023-11-09

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:

Sys.getenv(c("VAULT_ADDR", "VAULT_TOKEN", "VAULTR_AUTH_METHOD"))

##                             VAULT_ADDR                            VAULT_TOKEN 
##               "http://127.0.0.1:18200" "c008c70d-b623-2446-0a81-9e86bd756896" 
##                     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)

Reading, writing, listing and deleting secrets

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).

Alternative login approaches

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.

Username and password (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 (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 (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.