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
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 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.
Method capabilities_self()
As for the capabilities method, but for the
client token used to make the request.
Method capabilities_accessor()
As for the capabilities method, but using a
token accessor rather than a token itself.
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_self()
Returns information about the current client token
(as if calling $lookup with the token the client is using.
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.
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.
Method revoke()
Revokes a token and all child tokens. When the token is revoked, all dynamic secrets generated with it are also revoked.
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.
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.
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.
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 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.
Examples
server <- vaultr::vault_test_server(if_disabled = message)
#> ...waiting for Vault to start
#> ...waiting for Vault to start
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()
}
#> Verifying token
#> Error : 1 error occurred:
#> * invalid accessor
#>
#>