vault_client: Make a vault client

Description

Make a vault client. This must be done before accessing the vault. The default values for arguments are controlled by environment variables (see Details) and values provided as arguments override these defaults.

Usage

vault_client(
  login = FALSE,
  ...,
  addr = NULL,
  tls_config = NULL,
  namespace = NULL
)

Arguments

login: Login method. Specify a string to be passed along as the method argument to $login. The default FALSE means not to login. TRUE means to login using a default method specified by the environment variable VAULTR_AUTH_METHOD - if that variable is not set, an error is thrown. The value of NULL is the same as TRUE but does not throw an error if VAULTR_AUTH_METHOD is not set. Supported methods are token, github, approle, ldap, and userpass.
...: Additional arguments passed along to the authentication method indicated by login, if used.
addr: The vault address including protocol and port, e.g., https://vault.example.com:8200. If not given, the default is the environment variable VAULT_ADDR, which is the same as used by vault's command line client.
tls_config: TLS (https) configuration. For most uses this can be left blank. However, if your vault server uses a self-signed certificate you will need to provide this. Defaults to the environment variable VAULT_CAPATH, which is the same as vault's command line client.
namespace: A vault namespace, when using enterprise vault. If given, then this must be a string, and your vault must support namespaces, which is an enterprise feature. If the environment variable VAULT_NAMESPACE is set, we use that namespace when NULL is provided as an argument (this is the same variable as used by vault's command line client).

Environment variables

The creation of a client is affected by a number of environment variables, following the main vault command line client.

VAULT_ADDR: The url of the vault server. Must include a protocol (most likely https:// but in testing http:// might be used)
VAULT_CAPATH: The path to CA certificates
VAULT_TOKEN: A vault token to use in authentication. Only used for token-based authentication
VAULT_AUTH_GITHUB_TOKEN: As for the command line client, a github token for authentication using the github authentication backend
VAULTR_AUTH_METHOD: The method to use for authentication

Author

Rich FitzJohn

Super class

vaultr::vault_client_object -> vault_client

Public fields

auth: Authentication backends: vault_client_auth
audit: Audit methods: vault_client_audit
cubbyhole: The vault cubbyhole key-value store: vault_client_cubbyhole
operator: Operator methods: vault_client_operator
policy: Policy methods: vault_client_policy
secrets: Secret backends: vault_client_secrets
token: Token methods: vault_client_token
tools: Vault tools: vault_client_tools

Methods

Public methods

Inherited methods

Method `new()`

Create a new vault client. Not typically called directly, but via the vault_client method.

Usage

vault_client_$new(addr, tls_config, namespace)

Arguments

addr: The vault address, including protocol and port

tls_config

The TLS config, if used

namespace

The namespace, if used

Method `api()`

Returns an api client object that can be used to directly interact with the vault server.

Usage

vault_client_$api()

Method `read()`

Read a value from the vault. This can be used to read any value that you have permission to read, and can also be used as an interface to a version 1 key-value store (see vault_client_kv1. Similar to the vault CLI command vault read.

Usage

vault_client_$read(path, field = NULL, metadata = FALSE)

Arguments

path: Path for the secret to read, such as /secret/mysecret

field

Optional field to read from the secret. Each secret is stored as a key/value set (represented in R as a named list) and this is equivalent to using [[field]] on the return value. The default, NULL, returns the full set of values.

metadata

Logical, indicating if we should return metadata for this secret (lease information etc) as an attribute along with the values itself. Ignored if field is specified.

Method `write()`

Write data into the vault. This can be used to write any value that you have permission to write, and can also be used as an interface to a version 1 key-value store (see vault_client_kv1. Similar to the vault CLI command vault write.

Usage

vault_client_$write(path, data)

Arguments

path: Path for the secret to write, such as /secret/mysecret

data

A named list of values to write into the vault at this path. This replaces any existing values.

Method `delete()`

Delete a value from the vault

Usage

vault_client_$delete(path)

Arguments

path: The path to delete

Method `list()`

List data in the vault at a given path. This can be used to list keys, etc (e.g., at /secret).

Usage

vault_client_$list(path, full_names = FALSE)

Arguments

path: The path to list

full_names

Logical, indicating if full paths (relative to the vault root) should be returned.

Returns

A character vector (of zero length if no keys are found). Paths that are "directories" (i.e., that contain keys and could themselves be listed) will be returned with a trailing forward slash, e.g. path/

Method `login()`

Usage

vault_client_$login(
  ...,
  method = "token",
  mount = NULL,
  renew = FALSE,
  quiet = FALSE,
  token_only = FALSE,
  use_cache = TRUE
)

Arguments

...: Additional named parameters passed through to the underlying method

method

Authentication method to use, as a string. Supported values include token (the default), github, approle, ldap, and userpass.

mount

The mount path for the authentication backend, if it has been mounted in a nonstandard location. If not given, then it is assumed that the backend was mounted at a path corresponding to the method name.

renew

quiet

Suppress some informational messages

token_only

Logical, indicating that we do not want to actually log in, but instead just generate a token and return that. IF given then renew is ignored and we always generate a new token.

use_cache

Logical, indicating if we should look in the session cache for a token for this client. If this is TRUE then when we log in we save a copy of the token for this session and any subsequent calls to login at this vault address that use use_cache = TRUE will be able to use this token. Using cached tokens will make using some authentication backends that require authentication with external resources (e.g., github) much faster.

Method `status()`

Return the status of the vault server, including whether it is sealed or not, and the vault server version.

Usage

vault_client_$status()

Method `unwrap()`

Returns the original response inside the given wrapping token. The vault endpoints used by this method perform validation checks on the token, returns the original value on the wire rather than a JSON string representation of it, and ensures that the response is properly audit-logged.

Usage

vault_client_$unwrap(token)

Arguments

token: Specifies the wrapping token ID

Method `wrap_lookup()`

Look up properties of a wrapping token.

Usage

vault_client_$wrap_lookup(token)

Arguments

token: Specifies the wrapping token ID to lookup

Examples

Run this code



# We work with a test vault server here (see ?vault_test_server) for
# details.  To use it, you must have a vault binary installed on your
# system.  These examples will not affect any real running vault
# instance that you can connect to.
server <- vaultr::vault_test_server(if_disabled = message)

if (!is.null(server)) {
  # Create a vault_client object by providing the address of the vault
  # server.
  client <- vaultr::vault_client(addr = server$addr)

  # The client has many methods, grouped into a structure:
  client

  # For example, token related commands:
  client$token

  # The client is not authenticated by default:
  try(client$list("/secret"))

  # A few methods are unauthenticated and can still be run
  client$status()

  # Login to the vault, using the token that we know from the server -
  # ordinarily you would use a login approach suitable for your needs
  # (see the vault documentation).
  token <- server$token
  client$login(method = "token", token = token)

  # The vault contains no secrets at present
  client$list("/secret")

  # Secrets can contain any (reasonable) number of key-value pairs,
  # passed in as a list
  client$write("/secret/users/alice", list(password = "s3cret!"))

  # The whole list can be read out
  client$read("/secret/users/alice")
  # ...or just a field
  client$read("/secret/users/alice", "password")

  # Reading non-existant values returns NULL, not an error
  client$read("/secret/users/bob")

  client$delete("/secret/users/alice")
}

Run the code above in your browser using DataCamp Workspace

Description

Usage

Arguments

Environment variables

Author

Super class

Public fields

Methods

Public methods

Method new()

Usage

Arguments

Method api()

Usage

Method read()

Usage

Arguments

Method write()

Usage

Arguments

Method delete()

Usage

Arguments

Method list()

Usage

Arguments

Returns

Method login()

Usage

Arguments

Method status()

Usage

Method unwrap()

Usage

Arguments

Method wrap_lookup()

Usage

Arguments

Examples

Method `new()`

Method `api()`

Method `read()`

Method `write()`

Method `delete()`

Method `list()`

Method `login()`

Method `status()`

Method `unwrap()`

Method `wrap_lookup()`