---
title: "vaultr"
author: "Rich FitzJohn"
date: "2023-11-09"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{vaultr}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---



## 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"))
```

```
##                             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:

```r
vault <- vaultr::vault_client(login = TRUE, quiet = TRUE)
```

This creates an [`R6`](https://CRAN.R-project.org/package=R6)
object with methods for interacting with vault:

```r
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):

```r
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](https://www.vaultproject.io/docs/secrets/kv/kv-v1.html)
mounted at `/secret`.

List secrets with `$list`:

```r
vault$list("secret")
```

```
## [1] "database/"
```

```r
vault$list("secret/database")
```

```
## [1] "admin"    "readonly"
```

values that terminate in `/` are "directories".

Read secrets with `$read`:

```r
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:

```r
vault$read("secret/database/readonly", field = "value")
```

```
## [1] "passw0rd"
```

Delete secrets with `$delete`:

```r
vault$delete("secret/database/readonly")
```

After which the data is no longer available:

```r
vault$read("secret/database/readonly")
```

```
## NULL
```

Write new secrets with `$write`:

```r
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](https://www.vaultproject.io/docs/auth/index.html) 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](https://www.vaultproject.io/docs/auth/index.html)
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](https://www.vaultproject.io/docs/auth/userpass.html)
authentication and that a user `alice` exists with password
`p4ssw0rd`.

```r
cl <- vaultr::vault_client(login = "userpass", username = "alice",
                           password = "p4ssw0rd")
```

```
## ok, duration: 2764800 s (~32d)
```

```r
cl$read("secret/webserver")
```

```
## $password
## [1] "horsestaple"
```

This is obviously insecure!  `vaultr` can use
[`getPass`](https://cran.r-project.org/package=getPass) to securely
prompt for a password:

```r
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](https://developer.hashicorp.com/vault/docs/auth/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:

```r
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:

```r
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.
