Author: Rich FitzJohn
Date: 2023-11-09

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

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