vault_client_token: Vault Tokens
In vimc/vaultr: Vault Client for Secrets and Sensitive Data
vault_client_token R Documentation
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
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Inherited methods
Method new()
Create a vault_client_token object. Not typically
called by users.
Usage
vault_client_token$new(api_client)
Arguments
api_clientA 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
pathVector of paths on which capabilities are being
queried
tokenSingle 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
pathVector 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
pathVector of paths on which capabilities are being
queried
accessorAccessor 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_nameThe name of the token role
idThe ID of the client token. Can only be specified by
a root token. Otherwise, the token ID is a randomly generated
value
policiesA 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.
metaA named list of strings as metadata to pass through
to audit devices.
orphanLogical, 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_policyLogical, if TRUE, then the default
policy will not be contained in this token's policy set.
max_ttlProvides 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_nameThe display name of the token
num_usesMaximum 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.
periodIf 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.
ttlThe 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_ttlIndicates 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
tokenThe 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
accessorThe 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
tokenThe token to renew
incrementAn 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
incrementAn 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
tokenThe 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
accessorAccessor 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
tokenThe token to revoke
Method role_read()
Fetches the named role configuration.
Usage
vault_client_token$role_read(role_name)
Arguments
role_nameThe 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_nameName for the role - this will be used later to
refer to the role (e.g., in $create and other $role_*
methods.
allowed_policiesCharacter 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_policiesCharacter 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.
orphanIf 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.
periodA 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.
renewableSet 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_ttlAn 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_suffixA 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_cidrsCharacter 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_typeSpecifies 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_nameThe 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
tokenThe token to test
quietLogical 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()
}
vimc/vaultr documentation built on Nov. 11, 2023, 8:21 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| vault_client_token | R Documentation |
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
Inherited methods
Method new()
Create a vault_client_token object. Not typically
called by users.
Usage
vault_client_token$new(api_client)
Arguments
api_clientA 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
pathVector of paths on which capabilities are being queried
tokenSingle 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
pathVector 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
pathVector of paths on which capabilities are being queried
accessorAccessor 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_nameThe name of the token role
idThe ID of the client token. Can only be specified by a root token. Otherwise, the token ID is a randomly generated value
policiesA 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.
metaA named list of strings as metadata to pass through to audit devices.
orphanLogical, 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_policyLogical, if
TRUE, then the default policy will not be contained in this token's policy set.max_ttlProvides 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_nameThe display name of the token
num_usesMaximum 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.
periodIf specified, the token will be periodic; it will have no maximum TTL (unless a
max_ttlis also set) but every renewal will use the given period. Requires a root/sudo token to use.ttlThe 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_ttlIndicates 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,
vaultwill 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$unwrapmethod 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
tokenThe 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
accessorThe 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
tokenThe token to renew
incrementAn 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
incrementAn 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
tokenThe 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
accessorAccessor 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
tokenThe token to revoke
Method role_read()
Fetches the named role configuration.
Usage
vault_client_token$role_read(role_name)
Arguments
role_nameThe 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_nameName for the role - this will be used later to refer to the role (e.g., in
$createand other$role_*methods.allowed_policiesCharacter 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_policyis not set and "default" is not contained in disallowed_policies, the "default" policy will be added to the created token automatically.disallowed_policiesCharacter 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.
orphanIf
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.periodA 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.renewableSet to
FALSEto disable the ability of the token to be renewed past its initial TTL. The default value ofTRUEwill allow the token to be renewable up to the system/mount maximum TTL.explicit_max_ttlAn 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_suffixA 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_cidrsCharacter 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_typeSpecifies 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, thenservicetokens will be returned unless the client requests a batch type token at token creation time. Ifdefault-batch, thenbatchtokens 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_nameThe 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
tokenThe token to test
quietLogical scalar, set to
TRUEto 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()
}
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.