Tokens are the core method for authentication within Vault. Tokens can be used directly or dynamically generated by the auth methods. Regardless, the clients need valid tokens to interact with Vault.
As of Vault 1.0, there are two types of tokens: service tokens and batch tokens. The service tokens are persisted; therefore, they can be renewed or revoked before reaching its time-to-live (TTL). On the other hand, batch tokens are not persisted. They are encrypted binary large objects (blobs) that carry enough information for them to be used for Vault actions. Therefore, batch tokens are extremely lightweight and scalable; however, they lack most of the flexibility and features of service tokens.
»Service Tokens vs. Batch Tokens
As the number of machines and apps using Vault for secret management scales, Vault must manage the growing number of client tokens. The creation of service tokens can start affecting the Vault performance since they must be replicated across the primary and secondary clusters. On the other hand, batch tokens are neither persisted to disk nor live in memory, they are not a part of the data replication process.
Due to its lack of features with batch tokens (covered in Create batch tokens), it's preferable to use the service tokens in most use cases. However, think of a scenario where you have a large number of containers (e.g. 100,000s) start up and all request a token from Vault. The use of batch token can reduce the stress on the storage backend and improve the overall performance.
»Service Token Lifecycle
Every non-root token has a time-to-live (TTL) associated with it. When a token expires and it's not renewed, the token is automatically revoked by Vault.
When a new token or secret is created, it is a child of its creator. If the parent is revoked or expires, so do all its children regardless of their own TTLs.
Suppose a hierarchy exists with respective TTL as follows:
s.b519c6aa... (3h)
|___ s.6a2cf3e7... (4h)
|___ s.1d3fd4b2... (1h)
|___ s.794b6f2f... (2h)
In this scenario, the token s.1d3fd4b2..
will expire in an hour. If a
token or secret with a lease is not renewed before reaching its TTL, it will be
revoked by the Vault server. When it's revoked, it takes its child
(s.794b6f2f...
) although the child has one more hour before it expires. Then,
two hours later, s.b519c6aa...
will be revoked and takes its child
(s.6a2cf3e7...
) with it.
Refer to Tokens documentation for more details.
»Prerequisites
To perform the tasks described in this tutorial, you need to have a Vault environment. Refer to the Getting Started tutorial to install Vault.
NOTE: An interactive tutorial is also available if you do not have a Vault environment to perform the steps described in this tutorial. Click the Show Terminal button to start.
»Policy requirements
NOTE: For the purpose of this tutorial, you can use the root
token to
work with Vault. However, it is recommended that root tokens are used for just
enough initial setup or in emergencies. As a best practice, use tokens with an
appropriate set of policies based on your role in the organization.
To perform all tasks demonstrated in this tutorial, your policy must include the following permissions:
# List available auth method
path "sys/auth" {
capabilities = [ "read" ]
}
# Read default token configuration
path "sys/auth/token/tune" {
capabilities = [ "read", "sudo" ]
}
# Create and manage tokens (renew, lookup, revoke, etc.)
path "auth/token/*" {
capabilities = [ "create", "read", "update", "delete", "list", "sudo" ]
}
# For Advanced Features - list available secrets engines
path "sys/mounts" {
capabilities = [ "read" ]
}
# For Advanced Features - tune the database secrets engine TTL
path "sys/mounts/database/tune" {
capabilities = [ "update" ]
}
If you are not familiar with policies, complete the policies tutorial.
»Create service tokens with use limit
In addition to TTL and max TTL, tokens may be limited to a number of uses. Use limit tokens expire at the end of their last use regardless of their remaining TTLs. On the same note, use limit tokens expire at the end of their TTLs regardless of their remaining uses.
To create tokens with a use limit, set the number of uses when you create them.
Create a token with the -use-limit
property argument.
Example:
$ vault token create -policy=default -use-limit=2
Key Value
--- -----
token s.OZZFOsivUeOMeDyFtRz7cOmE
token_accessor OOHblEiweXu6ozNUk6GIOl5C
token_duration 768h
token_renewable true
token_policies ["default"]
identity_policies []
policies ["default"]
This creates a token with the default
policy and a use limit of 2.
»Verification
Set the
VAULT_TOKEN
value to the token you just generated, and invoke any CLI command.Example:
$ VAULT_TOKEN=s.OZZFOsivUeOMeDyFtRz7cOmE vault token lookup Key Value --- ----- accessor OOHblEiweXu6ozNUk6GIOl5C creation_time 1558033998 creation_ttl 768h display_name token entity_id n/a expire_time 2019-06-17T12:13:18.297964-07:00 explicit_max_ttl 0s id s.OZZFOsivUeOMeDyFtRz7cOmE issue_time 2019-05-16T12:13:18.297963-07:00 meta <nil> num_uses 1 # ...snip...
Notice that the
num_uses
is now1
.Run another CLI command.
$ VAULT_TOKEN=s.OZZFOsivUeOMeDyFtRz7cOmE vault write cubbyhole/token value=1234567890 Success! Data written to: cubbyhole/token
Try to read the value now using the same token.
$ VAULT_TOKEN=s.OZZFOsivUeOMeDyFtRz7cOmE vault read cubbyhole/token Error reading cubbyhole/token: Error making API request. URL: GET http://127.0.0.1:8200/v1/cubbyhole/token Code: 403. Errors: permission denied
The first command read the token's properties and then wrote a value to the cubbyhole secrets engine. This exhausted the use limit of 2 for this token. Therefore, the attempt to read the secret from the cubbyhole failed.
»Periodic service tokens
Root or sudo users have the ability to generate periodic tokens. Periodic tokens have a TTL (validity period), but no max TTL; therefore, they may live for an infinite duration of time so long as they are renewed within their TTL. This is useful for long-running services that cannot handle regenerating a token.
In this example, create a token role named "zabbix" with its period
set to
24 hours.
NOTE: When you set period
, it becomes the token renewal period (TTL).
When a period and an explicit max TTL were both set on a token, it behaves as a
periodic token. However, once the explicit max TTL is reached, the token will be
revoked. Refer to the Token settings to learn more about the period
and the maximum TTL.
Create a token role named
zabbix
with period set to 24 hours.$ vault write auth/token/roles/zabbix allowed_policies="default" period="24h"
Now, generate a token for a role,
zabbix
.$ vault token create -role=zabbix Key Value --- ----- token s.nRucA9Gtb3yNVmLUK22yzVKA token_accessor 4Nm9BvIVS4HWCgLATc3rIoiW token_duration 24h token_renewable true token_policies ["default"] identity_policies [] policies ["default"]
»Renew service tokens
You can renew the service token's TTL as long as it has not been expired.
To renew a token's TTL, execute the vault token renew
command.
$ vault token renew <TOKEN>
If you want to renew and extend the service token's TTL, pass the desired extension.
$ vault token renew -increment=<EXTENSION> <TOKEN>
The extension value can be an integer number of seconds (e.g. 3600) or a string duration (e.g. "1h").
»Revoke service tokens
If a user or machine needs a temporal access to Vault, you can set a short TTL or a number of uses to a service token so the token is automatically revoked at the end of its life. But if any suspicious activity was detected, Vault has built-in support for revocation of service tokens before reaching its TTL.
To revoke a specific token, execute the vault token revoke
command.
$ vault token revoke <TOKEN>
Example:
Revoke a service token, s.idqBWD6zx2eFJQKfDvNuSH3B
.
$ vault token revoke s.idqBWD6zx2eFJQKfDvNuSH3B
Instead of revoking using a token value, revoke tokens with a token
accessor,
5mus4HTbvVpI1VPaLK6eoQxy
.
$ vault token revoke -accessor 5mus4HTbvVpI1VPaLK6eoQxy
»Create short-lived tokens
Create a new service token with TTL of 60 seconds which means that the token gets automatically revoked after 60 seconds.
To view optional parameters to create tokens, run the command with -help
flag.
$ vault token create -help
There are a number of parameters you can set. To specify the token TTL, pass
the value using -ttl
parameter.
Example:
Create a token with TTL of 60 seconds.
$ vault token create -ttl=60s
Key Value
--- -----
token s.6XhDGuPwiJgCbQUIIei4uA1Z
token_accessor ykEJhiAP6KsP55IBQp6UaQqt
token_duration 1m
token_renewable true
token_policies ["root"]
identity_policies []
policies ["root"]
Lookup the token details.
$ vault token lookup s.6XhDGuPwiJgCbQUIIei4uA1Z
Key Value
--- -----
accessor ykEJhiAP6KsP55IBQp6UaQqt
creation_time 1558034505
creation_ttl 1m
display_name token
entity_id n/a
expire_time 2019-05-16T12:22:45.318019-07:00
explicit_max_ttl 0s
id s.6XhDGuPwiJgCbQUIIei4uA1Z
issue_time 2019-05-16T12:21:45.318019-07:00
meta <nil>
num_uses 0
orphan false
path auth/token/create
policies [root]
renewable true
ttl 38s
type service
NOTE: The vault token lookup
command returns the token's properties.
In this example, it shows that this token has 8 more seconds before it expires.
When you execute a Vault command using the new token immediately following its
creation, it should work. Wait for 60 seconds and try again. It returns
Code: 403. Errors:
which indicates a forbidden API call due to expired
token usage.
»Orphan tokens
Orphan tokens are not children of their parent; therefore, orphan tokens do not expire when their parent does.
NOTE: Orphan tokens still expire when their own max TTL is reached.
The following CLI command requires root token or sudo capability on the
auth/token/create
path.
$ vault token create -orphan
»Create batch tokens
Batch tokens are designed to be lightweight with limited flexibility. The following table highlights the difference.
Service Tokens | Batch Tokens | |
---|---|---|
Can be root tokens | Yes | No |
Can create child tokens | Yes | No |
Renewable | Yes | No |
Can be periodic | Yes | No |
Can have explicit Max TTL | Yes | No (always uses a fixed TTL) |
Has accessors | Yes | No |
Has Cubbyhole | Yes | No |
Revoked with parent (if not orphan) | Yes | Stops Working |
Dynamic secrets lease assignment | Self | Parent (if not orphan) |
Can be used across Performance Replication clusters | No | Yes |
Creation scales with performance standby node count | No | Yes |
Cost | Heavyweight; multiple storage writes per token creation | Lightweight; no storage cost for token creation |
To create a batch token, you need to explicitly set the token type to be
batch
and cannot beroot
. Create a batch token withtest
policy attached.$ vault token create -type=batch -policy=test Key Value --- ----- token b.AAAAAQL_tyer_gNuQqvQYPVQgsNxjap_YW1NB2m4CDHHadQo7rF2XLFGdw-NJplAZNKbfloOvifrbpRCGdgG1taTqmC7D-a_qftN64zeL10SmNwEoDTiPzC_1aS1KExbtVftU3Sx16cBVqaynwsYRDfVnfTAffE token_accessor n/a token_duration 768h token_renewable false token_policies ["test"] identity_policies [] policies ["test"]
Notice that the token value is much longer than the service tokens. This is because batch tokens are encrypted by the Vault's barrier.
Lookup the token details.
$ vault token lookup <batch_token> Key Value --- ----- accessor n/a creation_time 1539823898 creation_ttl 768h display_name token entity_id n/a expire_time 2018-11-18T16:51:38-08:00 explicit_max_ttl 0s id b.AAAAAQKEhArH0qEZze1AHljUq-ujPxQiuZS5VVTrPHtE9mthVu261PpyfcU28StDdLzNBmm5Tf7u5BC3oaiIyUxTxVq1B9SQgnPYnviuWaqlKJ4wzPkQcIyNTg2YdGobdlhaM8AIqbnSPGir5xQnsNRjve48w2c issue_time 2018-10-17T17:51:38-07:00 meta <nil> num_uses 0 orphan false path auth/token/create policies [default] renewable false ttl 767h59m49s type batch
Notice that the
renewable
is set tofalse
.Log in with the generated batch token.
$ vault login <batch_token>
Test to see if the token has a Cubbyhole.
$ vault write cubbyhole/token value="1234567890" Error writing data to cubbyhole/token: Error making API request. URL: PUT http://127.0.0.1:8200/v1/cubbyhole/token Code: 400. Errors: cubbyhole operations are only supported by "service" type tokens
Batch token cannot create child tokens even if its policy grants permission. Test to verify.
$ vault token create -policy=default Error creating token: Error making API request. URL: POST http://127.0.0.1:8200/v1/auth/token/create Code: 400. Errors: batch tokens cannot create more tokens
Log in with a highly privileged token such as
root
.$ vault login root
Try to revoke batch token.
$ vault token revoke <batch_token> Error revoking token: Error making API request. URL: PUT http://127.0.0.1:8200/v1/auth/token/revoke Code: 400. Errors: batch tokens cannot be revoked
Summary: There are some trade-offs for using batch tokens; however, depending on your use case, batch tokens improve the Vault performance significantly.
»Token settings
Token is a core authentication method in Vault with some default settings. This step demonstrates the following:
- View the current token settings
- Modify the default TTL and maximum TTL
Execute the following command to view the current settings on the
token
auth method.$ vault auth list -detailed Path Plugin Accessor Default TTL Max TTL Token Type ... ---- ------ -------- ----------- ------- ---------- ... token/ token auth_token_86f81f5c 2764800 2764800 default-service ... ...snip...
Alternatively, you can run the following command:
$ vault read sys/mounts/auth/token/tune Key Value --- ----- default_lease_ttl 768h force_no_cache false max_lease_ttl 768h token_type default-service
When no specific TTL was provided with the
vault token create
command, the generated token will inherit the default TTL which is 2764800 seconds (32 days). The same for the maximum TTL.Execute the following command to change the default TTL to 6 minutes and the max TTL to 24 hours.
$ vault write sys/mounts/auth/token/tune default_lease_ttl=6m max_lease_ttl=24h
Verify the token configuration.
$ vault read sys/mounts/auth/token/tune Key Value --- ----- default_lease_ttl 6m force_no_cache false max_lease_ttl 24h token_type default-service
Periodic Tokens: What if the period exceeds the default max TTL?
Let's execute the following command to examine the resulting behavior. First, update the zabbix role setting - the period is 72 hours.
$ vault write auth/token/roles/zabbix allowed_policies="default" period="72h"
Now, generate a token and see what happens.
$ vault token create -role=zabbix WARNING! The following warnings were returned from Vault: period of "72h0m0s" exceeded the effective max_ttl of "24h0m0s"; period value is capped accordingly Key Value --- ----- token s.AqJXvQsQiT2iqAJWKb4EDARs token_accessor onWpEZ0Ll9a4nkEBDO1x1ON5 token_duration 24h token_renewable true token_policies ["default"] identity_policies [] policies ["default"]
Notice the warning message. The max TTL configured on the
token
auth method is the hard max TTL.
»Apply token types
You've learned how you can fine tune the token's lifecycle. Now, let's talk about tokens for your applications. Vault clients first authenticate with Vault using an auth method to acquire a token.
There are auth methods aimed to authenticate applications or machines. Once its identity was verified, Vault server will return a token with appropriate policies attached.
Let's talk about AppRole auth method configuration.
»Generate periodic tokens
To configure the
approle
auth method to generate a periodic token for your app, first enable theapprole
auth method.$ vault auth enable approle
Create a role for your app specifying that the generated token should be periodic.
$ vault write auth/approle/role/jenkins policies="jenkins" period="72h"
This example defines a role named, "jenkins". The tokens generated for this role will be a periodic token with
jenkins
policy attached.
»Generate batch tokens
To configure the approle
auth method to generate a batch token for your
app, execute the following command.
$ vault write auth/approle/role/shipping policies="shipping" \
token_type="batch" \
token_ttl="60s"
This example defines a role named, "shipping". The tokens generated for this role will be a batch token with TTL of 1 minute.
»Tune the default TTLs
When you create tokens or leases with no specific TTL values, the default value applies to them.
$ vault auth list -detailed
Path Type Accessor Plugin Default TTL Max TTL ...
---- ---- -------- ------ ----------- -------
approle/ approle auth_approle_9592c1db n/a system system
ldap/ ldap auth_ldap_38571baa n/a system system
token/ token auth_token_47eac1f8 n/a system system
userpass/ userpass auth_userpass_6804c90e n/a system system
The system max TTL is 32 days, but you can override it to be longer or shorter in Vault's configuration.
Another option is to tune the mount configuration to override the system
defaults by calling the /sys/auth/<METHOD>/tune
endpoint.
Read the default TTL settings for token auth method.
$ vault read sys/auth/token/tune
Key Value
--- -----
default_lease_ttl 768h
force_no_cache false
max_lease_ttl 768h
token_type default-service
Notice that the token_type
is default-service
.
»Get the token count
To find out how many service tokens exist on a Vault environment, invoke the
sys/internal/counters/tokens
endpoint.
Example:
$ vault read sys/internal/counters/tokens
Key Value
--- -----
counters map[service_tokens:map[total:5]]