vault_client_token {vaultr}

Vault Tokens

Description

Vault Tokens

Vault Tokens

Details

Interact with vault's token methods. This includes support for querying, creating and deleting tokens. Tokens are fundamental to the way that vault works, so there are a lot of methods here. The vault documentation has a page devoted to token concepts: https://developer.hashicorp.com/vault/docs/concepts/tokens - there is also a page with commands: https://developer.hashicorp.com/vault/docs/commands/token - these have names very similar to the names used here.

Token Accessors

Many of the methods use "token accessors" - whenever a token is created, an "accessor" is created at the same time. This is another token that can be used to perform limited actions with the token such as

• Look up a token's properties (not including the actual token ID)

• Look up a token's capabilities on a path

• Revoke the token

However, accessors cannot be used to login, nor to retrieve the actual token itself.

Super class

vaultr::vault_client_object -> vault_client_token

Methods

Public methods

• vault_client_token$new()

• vault_client_token$list()

• vault_client_token$capabilities()

• vault_client_token$capabilities_self()

• vault_client_token$capabilities_accessor()

• vault_client_token$client()

• vault_client_token$create()

• vault_client_token$lookup()

• vault_client_token$lookup_self()

• vault_client_token$lookup_accessor()

• vault_client_token$renew()

• vault_client_token$renew_self()

• vault_client_token$revoke()

• vault_client_token$revoke_self()

• vault_client_token$revoke_accessor()

• vault_client_token$revoke_and_orphan()

• vault_client_token$role_read()

• vault_client_token$role_list()

• vault_client_token$role_write()

• vault_client_token$role_delete()

• vault_client_token$tidy()

• vault_client_token$login()

Inherited methods

• vaultr::vault_client_object$format()
• vaultr::vault_client_object$help()

Method new()

Create a vault_client_token object. Not typically called by users.

Usage

vault_client_token$new(api_client)

Arguments

api_client

A vault_api_client object

Method list()

List token accessors, returning a character vector

Usage

vault_client_token$list()

Method capabilities()

Fetch the capabilities of a token on the given paths. The capabilities returned will be derived from the policies that are on the token, and from the policies to which the token is entitled to through the entity and entity's group memberships.

Usage

vault_client_token$capabilities(path, token)

Arguments

path

Vector of paths on which capabilities are being queried

token

Single token for which capabilities are being queried

Method capabilities_self()

As for the capabilities method, but for the client token used to make the request.

Usage

vault_client_token$capabilities_self(path)

Arguments

path

Vector of paths on which capabilities are being queried

Method capabilities_accessor()

As for the capabilities method, but using a token accessor rather than a token itself.

Usage

vault_client_token$capabilities_accessor(path, accessor)

Arguments

path

Vector of paths on which capabilities are being queried

accessor

Accessor of the token for which capabilities are being queried

Method client()

Return the current client token

Usage

vault_client_token$client()

Method create()

Create a new token

Usage

vault_client_token$create(
  role_name = NULL,
  id = NULL,
  policies = NULL,
  meta = NULL,
  orphan = FALSE,
  no_default_policy = FALSE,
  max_ttl = NULL,
  display_name = NULL,
  num_uses = 0L,
  period = NULL,
  ttl = NULL,
  wrap_ttl = NULL
)

Arguments

role_name

The name of the token role

id

The ID of the client token. Can only be specified by a root token. Otherwise, the token ID is a randomly generated value

policies

A character vector of policies for the token. This must be a subset of the policies belonging to the token making the request, unless root. If not specified, defaults to all the policies of the calling token.

meta

A named list of strings as metadata to pass through to audit devices.

orphan

Logical, indicating if the token created should be an orphan (they will have no parent). As such, they will not be automatically revoked by the revocation of any other token.

no_default_policy

Logical, if TRUE, then the default policy will not be contained in this token's policy set.

max_ttl

Provides a maximum lifetime for any tokens issued against this role, including periodic tokens. Unlike direct token creation, where the value for an explicit max TTL is stored in the token, for roles this check will always use the current value set in the role. The main use of this is to provide a hard upper bound on periodic tokens, which otherwise can live forever as long as they are renewed. This is an integer number of seconds

display_name

The display name of the token

num_uses

Maximum number of uses that a token can have. This can be used to create a one-time-token or limited use token. The default, or the value of 0, has no limit to the number of uses.

period

If specified, the token will be periodic; it will have no maximum TTL (unless a max_ttl is also set) but every renewal will use the given period. Requires a root/sudo token to use.

ttl

The TTL period of the token, provided as "1h", where hour is the largest suffix. If not provided, the token is valid for the default lease TTL, or indefinitely if the root policy is used.

wrap_ttl

Indicates that the secret should be wrapped. This is discussed in the vault documentation: https://developer.hashicorp.com/vault/docs/concepts/response-wrapping When this option is used, vault will take the response it would have sent to an HTTP client and instead insert it into the cubbyhole of a single-use token, returning that single-use token instead. Logically speaking, the response is wrapped by the token, and retrieving it requires an unwrap operation against this token (see the ⁠$unwrap⁠ method vault_client. Must be specified as a valid duration (e.g., ⁠1h⁠).

Method lookup()

Returns information about the client token

Usage

vault_client_token$lookup(token = NULL)

Arguments

token

The token to lookup

Method lookup_self()

Returns information about the current client token (as if calling ⁠$lookup⁠ with the token the client is using.

Usage

vault_client_token$lookup_self()

Method lookup_accessor()

Returns information about the client token from the accessor.

Usage

vault_client_token$lookup_accessor(accessor)

Arguments

accessor

The token accessor to lookup

Method renew()

Renews a lease associated with a token. This is used to prevent the expiration of a token, and the automatic revocation of it. Token renewal is possible only if there is a lease associated with it.

Usage

vault_client_token$renew(token, increment = NULL)

Arguments

token

The token to renew

increment

An optional requested lease increment can be provided. This increment may be ignored. If given, it should be a duration (e.g., ⁠1h⁠).

Method renew_self()

Renews a lease associated with the calling token. This is used to prevent the expiration of a token, and the automatic revocation of it. Token renewal is possible only if there is a lease associated with it. This is equivalent to calling ⁠$renew()⁠ with the client token.

Usage

vault_client_token$renew_self(increment = NULL)

Arguments

increment

An optional requested lease increment can be provided. This increment may be ignored. If given, it should be a duration (e.g., ⁠1h⁠).

Method revoke()

Revokes a token and all child tokens. When the token is revoked, all dynamic secrets generated with it are also revoked.

Usage

vault_client_token$revoke(token)

Arguments

token

The token to revoke

Method revoke_self()

Revokes the token used to call it and all child tokens. When the token is revoked, all dynamic secrets generated with it are also revoked. This is equivalent to calling ⁠$revoke()⁠ with the client token.

Usage

vault_client_token$revoke_self()

Method revoke_accessor()

Revoke the token associated with the accessor and all the child tokens. This is meant for purposes where there is no access to token ID but there is need to revoke a token and its children.

Usage

vault_client_token$revoke_accessor(accessor)

Arguments

accessor

Accessor of the token to revoke.

Method revoke_and_orphan()

Revokes a token but not its child tokens. When the token is revoked, all secrets generated with it are also revoked. All child tokens are orphaned, but can be revoked subsequently using /auth/token/revoke/. This is a root-protected method.

Usage

vault_client_token$revoke_and_orphan(token)

Arguments

token

The token to revoke

Method role_read()

Fetches the named role configuration.

Usage

vault_client_token$role_read(role_name)

Arguments

role_name

The name of the token role.

Method role_list()

List available token roles.

Usage

vault_client_token$role_list()

Method role_write()

Creates (or replaces) the named role. Roles enforce specific behaviour when creating tokens that allow token functionality that is otherwise not available or would require sudo/root privileges to access. Role parameters, when set, override any provided options to the create endpoints. The role name is also included in the token path, allowing all tokens created against a role to be revoked using the ⁠/sys/leases/revoke-prefix⁠ endpoint.

Usage

vault_client_token$role_write(
  role_name,
  allowed_policies = NULL,
  disallowed_policies = NULL,
  orphan = NULL,
  period = NULL,
  renewable = NULL,
  explicit_max_ttl = NULL,
  path_suffix = NULL,
  bound_cidrs = NULL,
  token_type = NULL
)

Arguments

role_name

Name for the role - this will be used later to refer to the role (e.g., in ⁠$create⁠ and other ⁠$role_*⁠ methods.

allowed_policies

Character vector of policies allowed for this role. If set, tokens can be created with any subset of the policies in this list, rather than the normal semantics of tokens being a subset of the calling token's policies. The parameter is a comma-delimited string of policy names. If at creation time no_default_policy is not set and "default" is not contained in disallowed_policies, the "default" policy will be added to the created token automatically.

disallowed_policies

Character vector of policies forbidden for this role. If set, successful token creation via this role will require that no policies in the given list are requested. Adding "default" to this list will prevent "default" from being added automatically to created tokens.

orphan

If TRUE, then tokens created against this policy will be orphan tokens (they will have no parent). As such, they will not be automatically revoked by the revocation of any other token.

period

A duration (e.g., ⁠1h⁠). If specified, the token will be periodic; it will have no maximum TTL (unless an "explicit-max-ttl" is also set) but every renewal will use the given period. Requires a root/sudo token to use.

renewable

Set to FALSE to disable the ability of the token to be renewed past its initial TTL. The default value of TRUE will allow the token to be renewable up to the system/mount maximum TTL.

explicit_max_ttl

An integer number of seconds. Provides a maximum lifetime for any tokens issued against this role, including periodic tokens. Unlike direct token creation, where the value for an explicit max TTL is stored in the token, for roles this check will always use the current value set in the role. The main use of this is to provide a hard upper bound on periodic tokens, which otherwise can live forever as long as they are renewed. This is an integer number of seconds.

path_suffix

A string. If set, tokens created against this role will have the given suffix as part of their path in addition to the role name. This can be useful in certain scenarios, such as keeping the same role name in the future but revoking all tokens created against it before some point in time. The suffix can be changed, allowing new callers to have the new suffix as part of their path, and then tokens with the old suffix can be revoked via ⁠/sys/leases/revoke-prefix⁠.

bound_cidrs

Character vector of CIDRS. If set, restricts usage of the generated token to client IPs falling within the range of the specified CIDR(s). Unlike most other role parameters, this is not reevaluated from the current role value at each usage; it is set on the token itself. Root tokens with no TTL will not be bound by these CIDRs; root tokens with TTLs will be bound by these CIDRs.

token_type

Specifies the type of tokens that should be returned by the role. If either service or batch is specified, that kind of token will always be returned. If default-service, then service tokens will be returned unless the client requests a batch type token at token creation time. If default-batch, then batch tokens will be returned unless the client requests a service type token at token creation time.

Method role_delete()

Delete a named token role

Usage

vault_client_token$role_delete(role_name)

Arguments

role_name

The name of the role to delete

Method tidy()

Performs some maintenance tasks to clean up invalid entries that may remain in the token store. Generally, running this is not needed unless upgrade notes or support personnel suggest it. This may perform a lot of I/O to the storage method so should be used sparingly.

Usage

vault_client_token$tidy()

Method login()

Unlike other auth backend login methods, this does not actually log in to the vault. Instead it verifies that a token can be used to communicate with the vault.

Usage

vault_client_token$login(token = NULL, quiet = FALSE)

Arguments

token

The token to test

quiet

Logical scalar, set to TRUE to suppress informational messages.

Examples

server <- vaultr::vault_test_server(if_disabled = message)
if (!is.null(server)) {
  client <- server$client()

  # There are lots of token methods here:
  client$token

  # To demonstrate, it will be useful to create a restricted
  # policy that can only read from the /secret path
  rules <- 'path "secret/*" {policy = "read"}'
  client$policy$write("read-secret", rules)
  client$write("/secret/path", list(key = "value"))

  # Create a token that has this policy
  token <- client$auth$token$create(policies = "read-secret")
  alice <- vaultr::vault_client(addr = server$addr)
  alice$login(method = "token", token = token)
  alice$read("/secret/path")

  client$token$lookup(token)

  # We can query the capabilities of this token
  client$token$capabilities("secret/path", token)

  # Tokens are not safe to pass around freely because they *are*
  # the ability to login, but the `token$create` command also
  # provides an accessor:
  accessor <- attr(token, "info")$accessor

  # It is not possible to derive the token from the accessor, but
  # we can use the accessor to ask vault what it could do if it
  # did have the token (and do things like revoke the token)
  client$token$capabilities_accessor("secret/path", accessor)

  client$token$revoke_accessor(accessor)
  try(client$token$capabilities_accessor("secret/path", accessor))

  # cleanup
  server$kill()
}