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