»Tokens and Leases
Almost everything in Vault has an associated lease, and when the lease is
expired, the secret is revoked. Tokens are not an exception. 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.
»Lease Hierarchy
When a new token or secret is created, it is a child of the creator. If the
parent is revoked or expires, so do all its children regardless of their own
leases. A child may be a token, secret, or authentication created by a parent. A
parent is almost always a token.
Suppose a hierarchy exists with respective TTL as follows:
b519c6aa... (3h)
6a2cf3e7... (4h)
1d3fd4b2... (1h)
794b6f2f... (2h)
b519c6aa... (3h) 6a2cf3e7... (4h) 1d3fd4b2... (1h) 794b6f2f... (2h)
In this scenario, the lease ID of 1d3fd4b2..
will expire in an hour. If a
token or secret with a lease is not renewed before the lease expires, it will be
revoked by the Vault server. When it's revoked, it takes its child
(794b6f2f...
) although the child has one more hour before it expires. Then,
two hours later, b519c6aa...
will be revoked and takes its child
(6a2cf3e7...
) with it.
»Reference Material
NOTE: An interactive
tutorial is
also available if you do not have a Vault environment to perform the steps
described in this guide.
»Estimated Time to Complete
10 minutes
»Personas
The end-to-end scenario described in this guide involves one persona:
-
admin
with privileged permissions to create and manage tokens
See the policy requirements section for details.
»Challenge
Consider the following scenarios often encountered outside of Vault:
- There is no break glass procedure available for revoking
access to credentials in the event of a breach
- Credentials for external systems (e.g. AWS, MySQL) are shared
- Need temporal access to a database in a specific scenario
»Solution
Vault has built-in support for secret revocation. Vault can revoke not only
a single secret, but also a tree of secrets. For example, Vault can revoke all
secrets read by a specific user or all secrets of a specific type.
Revocation assists in key rolling as well as locking down systems in the case of
an intrusion.
If a user or machine needs a temporal access to Vault, you can set a short TTL
or a number of uses to a token so the token is automatically revoked at the
end of its life.
This also allows for organizations to plan and train for various
"break glass" procedures.
»Prerequisites
To perform the tasks described in this guide, you need to have a Vault
environment. Refer to the Getting
Started guide to install Vault. Make sure
that your Vault server has been initialized and
unsealed.
»Policy requirements
NOTE: For the purpose of this guide, 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 guide, your policy must include the
following permissions:
path "sys/auth" {
capabilities = [ "read" ]
}
path "sys/auth/token/tune" {
capabilities = [ "read", "sudo" ]
}
path "auth/token/*" {
capabilities = [ "create", "read", "update", "delete", "list", "sudo" ]
}
path "sys/mounts" {
capabilities = [ "read" ]
}
path "sys/mounts/database/tune" {
capabilities = [ "update" ]
}
path "sys/auth" { capabilities = [ "read" ]}
path "sys/auth/token/tune" { capabilities = [ "read", "sudo" ]}
path "auth/token/*" { capabilities = [ "create", "read", "update", "delete", "list", "sudo" ]}
path "sys/mounts" { capabilities = [ "read" ]}
path "sys/mounts/database/tune" { capabilities = [ "update" ]}
If you are not familiar with policies, complete the
policies guide.
»Steps
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.
This guide demonstrates the lifecycle of tokens.
- Read token auth method configuration
- Create short-lived tokens
- Create tokens with use limit
- Periodic tokens
- Orphan tokens
- Revoke tokens
»Step 1: Read token auth method configuration
When you create leases with no specific TTL values, the default value applies
to the lease.
$ vault auth list
Path Type Accessor Default TTL Max TTL Replication Behavior Description
approle/ approle auth_approle_53f0fb08 system system replicated
github/ github auth_github_b770f4c8 system system replicated
token/ token auth_token_2ad69043 system system replicated token based credentials
userpass/ userpass auth_userpass_d326d2f9 system system replicated
$ vault auth list
Path Type Accessor Default TTL Max TTL Replication Behavior Descriptionapprole/ approle auth_approle_53f0fb08 system system replicatedgithub/ github auth_github_b770f4c8 system system replicatedtoken/ token auth_token_2ad69043 system system replicated token based credentialsuserpass/ userpass auth_userpass_d326d2f9 system system replicated
The system max TTL is 32 days, but you can override it to be longer or
shorter in Vault's configuration file.
Another option is to tune the mount configuration to override the system
defaults by calling the /sys/mounts/<PATH>/tune
endpoint (e.g.
/sys/mounts/database/tune
). For the auth method system configuration, call
/sys/auth/<METHOD>/tune
endpoint.
NOTE: Refer to the Advanced Features section for tuning
the system configuration.
»CLI command
Read the default TTL settings for token auth method:
$ vault read sys/auth/token/tune
Key Value
--- -----
default_lease_ttl 2764800
force_no_cache false
max_lease_ttl 2764800
$ vault read sys/auth/token/tune
Key Value--- -----default_lease_ttl 2764800force_no_cache falsemax_lease_ttl 2764800
»API call using cURL
Use /sys/auth/token/tune
endpoint to read the default TTL settings for token auth
method:
$ curl --header "X-Vault-Token: <TOKEN>" \
--request GET \
<VAULT_ADDRESS>/v1/sys/auth/token/tune
$ curl --header "X-Vault-Token: <TOKEN>" \ --request GET \ <VAULT_ADDRESS>/v1/sys/auth/token/tune
Where <TOKEN>
is your valid token with read permission on the
sys/auth/token/tune
path.
Example:
$ curl --header "X-Vault-Token: ..." --request GET \
http://127.0.0.1:8200/v1/sys/auth/token/tune | jq
{
"default_lease_ttl": 2764800,
"max_lease_ttl": 2764800,
"force_no_cache": false,
"request_id": "630fd49d-f704-540f-0641-41516087654f",
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": {
"default_lease_ttl": 2764800,
"force_no_cache": false,
"max_lease_ttl": 2764800
},
"wrap_info": null,
"warnings": null,
"auth": null
}
$ curl --header "X-Vault-Token: ..." --request GET \ http://127.0.0.1:8200/v1/sys/auth/token/tune | jq{ "default_lease_ttl": 2764800, "max_lease_ttl": 2764800, "force_no_cache": false, "request_id": "630fd49d-f704-540f-0641-41516087654f", "lease_id": "", "renewable": false, "lease_duration": 0, "data": { "default_lease_ttl": 2764800, "force_no_cache": false, "max_lease_ttl": 2764800 }, "wrap_info": null, "warnings": null, "auth": null}
NOTE: The returned TTL value is in seconds (2764800 seconds = 32 days).
»Step 2: Create short-lived tokens
Create a new token with TTL of 30 seconds which means that the token gets
automatically revoked after 30 seconds.
»CLI command
To view optional parameters to create tokens:
$ vault token create -help
$ 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:
$ vault token create -ttl=30s
Key Value
--- -----
token 3b2b1285-844b-4b40-6afa-623f39c1b738
token_accessor 2b2b5b83-7f22-fecd-03f0-4e25bf64da11
token_duration 30s
token_renewable true
token_policies [admin]
$ VAULT_TOKEN=3b2b1285-844b-4b40-6afa-623f39c1b738 vault token lookup
Key Value
--- -----
accessor 2b2b5b83-7f22-fecd-03f0-4e25bf64da11
creation_time 1515702047
creation_ttl 30
display_name token
expire_time 2018-01-11T20:21:17.900969673Z
explicit_max_ttl 0
id 3b2b1285-844b-4b40-6afa-623f39c1b738
issue_time 2018-01-11T20:20:47.90096937Z
meta <nil>
num_uses 0
orphan false
path auth/token/create
policies [admin]
renewable true
ttl 8
$ vault token create -ttl=30sKey Value--- -----token 3b2b1285-844b-4b40-6afa-623f39c1b738token_accessor 2b2b5b83-7f22-fecd-03f0-4e25bf64da11token_duration 30stoken_renewable truetoken_policies [admin]
$ VAULT_TOKEN=3b2b1285-844b-4b40-6afa-623f39c1b738 vault token lookupKey Value--- -----accessor 2b2b5b83-7f22-fecd-03f0-4e25bf64da11creation_time 1515702047creation_ttl 30display_name tokenexpire_time 2018-01-11T20:21:17.900969673Zexplicit_max_ttl 0id 3b2b1285-844b-4b40-6afa-623f39c1b738issue_time 2018-01-11T20:20:47.90096937Zmeta <nil>num_uses 0orphan falsepath auth/token/createpolicies [admin]renewable truettl 8
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 30 seconds and try again. It returns
Code: 403. Errors:
which indicates a forbidden API call due to expired
token usage.
You can renew the token's TTL as long as the token has not expired.
$ vault token renew <TOKEN>
$ vault token renew <TOKEN>
If you want to renew and extend the token's TTL, pass the desired extension:
$ vault token renew <TOKEN> <EXTENSION>
$ vault token renew <TOKEN> <EXTENSION>
Or with revamped cli:
$ vault token renew -increment=<EXTENSION> <TOKEN>
$ 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").
»API call using cURL
Use the auth/token/create
endpoint to create a new token. There are a number of
optional parameters that you can pass
in the request payload.
Example:
The following example sets the ttl
parameter.
$ curl --header "X-Vault-Token: ..." --request POST \
--data '{"ttl": "30s"}' \
http://127.0.0.1:8200/v1/auth/token/create | jq
{
...
"auth": {
"client_token": "f7d88963-1aba-64d7-11a0-9282ae7681d0",
"accessor": "c0a40d94-b814-e46f-7e56-ee18fccdf1b6",
"policies": [
"admin"
],
"metadata": null,
"lease_duration": 30,
"renewable": true
}
}
$ curl --header "X-Vault-Token: f7d88963-1aba-64d7-11a0-9282ae7681d0" \
--request GET \
http://127.0.0.1:8200/v1/auth/token/lookup-self | jq
{
...
"data": {
"accessor": "c0a40d94-b814-e46f-7e56-ee18fccdf1b6",
"creation_time": 1515702669,
"creation_ttl": 30,
...
"renewable": true,
"ttl": 14
},
...
}
$ curl --header "X-Vault-Token: ..." --request POST \ --data '{"ttl": "30s"}' \ http://127.0.0.1:8200/v1/auth/token/create | jq{ ... "auth": { "client_token": "f7d88963-1aba-64d7-11a0-9282ae7681d0", "accessor": "c0a40d94-b814-e46f-7e56-ee18fccdf1b6", "policies": [ "admin" ], "metadata": null, "lease_duration": 30, "renewable": true }}
$ curl --header "X-Vault-Token: f7d88963-1aba-64d7-11a0-9282ae7681d0" \ --request GET \ http://127.0.0.1:8200/v1/auth/token/lookup-self | jq{ ... "data": { "accessor": "c0a40d94-b814-e46f-7e56-ee18fccdf1b6", "creation_time": 1515702669, "creation_ttl": 30, ... "renewable": true, "ttl": 14 }, ...}
When you invoke the API using the new token immediately following its
creation, it should work. Wait for 30 seconds and try again. It returns
Code: 403. Errors:
which indicates a forbidden API call due to expired
token usage.
»Renew the token:
$ curl --header "X-Vault-Token: ..." --request POST \
http://127.0.0.1:8200/v1/auth/token/renew/<TOKEN> | jq
# Renew token with 1 hour extension
$ curl --header "X-Vault-Token: ..." --request POST \
--data '{"increment": "3600"}' \
http://127.0.0.1:8200/v1/auth/token/renew/<TOKEN> | jq
$ curl --header "X-Vault-Token: ..." --request POST \ http://127.0.0.1:8200/v1/auth/token/renew/<TOKEN> | jq
# Renew token with 1 hour extension$ curl --header "X-Vault-Token: ..." --request POST \ --data '{"increment": "3600"}' \ http://127.0.0.1:8200/v1/auth/token/renew/<TOKEN> | jq
NOTE: Tokens can be renewed as long as its life hasn't reached its max
TTL. For example, if the token's TTL is 1 hour and max TTL is 24 hours, you can
renew the token up to 24 hours from its creation time. Once 24 hours has passed from
the token's creation time, the token is revoked by Vault. For long running
processes, this may introduce complexity. In such case, use periodic tokens.
»Step 3: Create 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.
»CLI command
Create a token with the -use-limit
property argument.
Example:
$ vault token create -policy=default -use-limit=2
Key Value
--- -----
token bd39178e-176e-cc91-3930-94f7b0194de5
token_accessor a230f5ab-b59f-db0b-855d-36ea4319b58e
token_duration 768h0m0s
token_renewable true
token_policies [default]
$ vault token create -policy=default -use-limit=2
Key Value--- -----token bd39178e-176e-cc91-3930-94f7b0194de5token_accessor a230f5ab-b59f-db0b-855d-36ea4319b58etoken_duration 768h0m0stoken_renewable truetoken_policies [default]
This creates a token with the default policy and a use limit of 2.
»Verification
$ VAULT_TOKEN=bd39178e-176e-cc91-3930-94f7b0194de5 vault token lookup
Key Value
--- -----
accessor a230f5ab-b59f-db0b-855d-36ea4319b58e
creation_time 1515710251
creation_ttl 2764800
display_name token
expire_time 2018-02-12T22:37:31.715486503Z
explicit_max_ttl 0
id bd39178e-176e-cc91-3930-94f7b0194de5
issue_time 2018-01-11T22:37:31.715486221Z
meta <nil>
num_uses 1
orphan false
path auth/token/create
policies [default]
renewable true
ttl 2764769
$ VAULT_TOKEN=bd39178e-176e-cc91-3930-94f7b0194de5 vault write cubbyhole/token \
value=bd39178e-176e-cc91-3930-94f7b0194de5
Success! Data written to: cubbyhole/token
$ VAULT_TOKEN=bd39178e-176e-cc91-3930-94f7b0194de5 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
$ VAULT_TOKEN=bd39178e-176e-cc91-3930-94f7b0194de5 vault token lookup
Key Value--- -----accessor a230f5ab-b59f-db0b-855d-36ea4319b58ecreation_time 1515710251creation_ttl 2764800display_name tokenexpire_time 2018-02-12T22:37:31.715486503Zexplicit_max_ttl 0id bd39178e-176e-cc91-3930-94f7b0194de5issue_time 2018-01-11T22:37:31.715486221Zmeta <nil>num_uses 1orphan falsepath auth/token/createpolicies [default]renewable truettl 2764769
$ VAULT_TOKEN=bd39178e-176e-cc91-3930-94f7b0194de5 vault write cubbyhole/token \ value=bd39178e-176e-cc91-3930-94f7b0194de5
Success! Data written to: cubbyhole/token
$ VAULT_TOKEN=bd39178e-176e-cc91-3930-94f7b0194de5 vault read cubbyhole/tokenError reading cubbyhole/token: Error making API request.
URL: GET http://127.0.0.1:8200/v1/cubbyhole/tokenCode: 403. Errors:
* permission denied
The first command read the token's properties and then wrote a value to the cubbyhole
secret engine. This exhausted the use limit of 2 for this token. Therefore,
the attempt to read the secret from the cubbyhole failed.
»API call using cURL
Set the num_uses
property in the request payload.
$ curl --header "X-Vault-Token: ..." --request POST \
--data '{ "policies": ["default"], "num_uses":2 }' \
http://127.0.0.1:8200/v1/auth/token/create | jq
{
"request_id": "0e98ff80-2825-7f50-6522-b6f95d596ef4",
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": null,
"wrap_info": null,
"warnings": null,
"auth": {
"client_token": "d9c2f2e5-6b8a-4021-476c-ebd3f166d668",
"accessor": "4dd5ef0d-8515-c3ae-ea49-016c3e9eb968",
"policies": [
"default"
],
"metadata": null,
"lease_duration": 2764800,
"renewable": true
}
}
$ curl --header "X-Vault-Token: ..." --request POST \ --data '{ "policies": ["default"], "num_uses":2 }' \ http://127.0.0.1:8200/v1/auth/token/create | jq{ "request_id": "0e98ff80-2825-7f50-6522-b6f95d596ef4", "lease_id": "", "renewable": false, "lease_duration": 0, "data": null, "wrap_info": null, "warnings": null, "auth": { "client_token": "d9c2f2e5-6b8a-4021-476c-ebd3f166d668", "accessor": "4dd5ef0d-8515-c3ae-ea49-016c3e9eb968", "policies": [ "default" ], "metadata": null, "lease_duration": 2764800, "renewable": true }}
This creates a token with the default policy and a use limit of 2.
»Verification
$ curl --header "X-Vault-Token: d9c2f2e5-6b8a-4021-476c-ebd3f166d668" \
--request GET \
http://127.0.0.1:8200/v1/auth/token/lookup-self | jq
{
"request_id": "77be1321-c0ca-e099-6f92-4ad87133b044",
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": {
"accessor": "4dd5ef0d-8515-c3ae-ea49-016c3e9eb968",
"creation_time": 1515711922,
"creation_ttl": 2764800,
"display_name": "token",
"expire_time": "2018-02-12T23:05:22.746137253Z",
"explicit_max_ttl": 0,
"id": "d9c2f2e5-6b8a-4021-476c-ebd3f166d668",
"issue_time": "2018-01-11T23:05:22.746136892Z",
"meta": null,
"num_uses": 1,
...
}
$ curl --header "X-Vault-Token: d9c2f2e5-6b8a-4021-476c-ebd3f166d668" \
--request POST \
--data '{ "value": "d9c2f2e5-6b8a-4021-476c-ebd3f166d668" }' \
http://127.0.0.1:8200/v1/cubbyhole/token
$ curl --header "X-Vault-Token: d9c2f2e5-6b8a-4021-476c-ebd3f166d668" \
--request GET \
http://127.0.0.1:8200/v1/cubbyhole/token | jq
{
"errors": [
"permission denied"
]
}
$ curl --header "X-Vault-Token: d9c2f2e5-6b8a-4021-476c-ebd3f166d668" \ --request GET \ http://127.0.0.1:8200/v1/auth/token/lookup-self | jq{ "request_id": "77be1321-c0ca-e099-6f92-4ad87133b044", "lease_id": "", "renewable": false, "lease_duration": 0, "data": { "accessor": "4dd5ef0d-8515-c3ae-ea49-016c3e9eb968", "creation_time": 1515711922, "creation_ttl": 2764800, "display_name": "token", "expire_time": "2018-02-12T23:05:22.746137253Z", "explicit_max_ttl": 0, "id": "d9c2f2e5-6b8a-4021-476c-ebd3f166d668", "issue_time": "2018-01-11T23:05:22.746136892Z", "meta": null, "num_uses": 1, ...}
$ curl --header "X-Vault-Token: d9c2f2e5-6b8a-4021-476c-ebd3f166d668" \ --request POST \ --data '{ "value": "d9c2f2e5-6b8a-4021-476c-ebd3f166d668" }' \ http://127.0.0.1:8200/v1/cubbyhole/token
$ curl --header "X-Vault-Token: d9c2f2e5-6b8a-4021-476c-ebd3f166d668" \ --request GET \ http://127.0.0.1:8200/v1/cubbyhole/token | jq{ "errors": [ "permission denied" ]}
The first command read the token's properties and then wrote a value to the cubbyhole
secret engine. This exhausted the use limit of 2 for this token. Therefore,
the attempt to read the secret from the cubbyhole failed.
»Step 4: Periodic tokens
Root or sudo users have the ability to generate periodic tokens.
Periodic tokens have a TTL, 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.
»CLI command
First, create a token role with a specific period
. When you set period
,
tokens created for this role will have no max TTL. Instead, the period
becomes
the token renewal period. This value can be an integer value in seconds (e.g.
- or a string duration (e.g. 72h).
$ vault write auth/token/roles/<ROLE_NAME> allowed_policies="<POLICY_NAMES>" period=<RENEWAL_PERIOD>
$ vault write auth/token/roles/<ROLE_NAME> allowed_policies="<POLICY_NAMES>" period=<RENEWAL_PERIOD>
Example:
$ vault write auth/token/roles/zabbix allowed_policies="default" period="24h"
$ vault write auth/token/roles/zabbix allowed_policies="default" period="24h"
Now, generate a token:
$ vault token create -role=zabbix
Key Value
--- -----
token de91ebba-20ad-18ba-fa43-08e1932de301
token_accessor 1f8abad0-c1db-9399-15ee-dd4b6230386c
token_duration 24h0m0s
token_renewable true
token_policies [default]
$ vault token create -role=zabbix
Key Value--- -----token de91ebba-20ad-18ba-fa43-08e1932de301token_accessor 1f8abad0-c1db-9399-15ee-dd4b6230386ctoken_duration 24h0m0stoken_renewable truetoken_policies [default]
»API call using cURL
First, create a token role by setting period
. When you set period
, tokens
created for this role will have no max TTL. Instead, the period
becomes the
token renewal period. This value can be an integer value in seconds (e.g.
- or a string duration (e.g. 72h).
Example:
$ tee payload.json <<EOF
{
"allowed_policies": [
"default"
],
"period": "24h"
}
EOF
$ curl --header "X-Vault-Token: ..." --request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/token/roles/zabbix
$ tee payload.json <<EOF{ "allowed_policies": [ "default" ], "period": "24h"}EOF
$ curl --header "X-Vault-Token: ..." --request POST \ --data @payload.json \ http://127.0.0.1:8200/v1/auth/token/roles/zabbix
This creates a token role named zabbix
with default
policies attached.
Its renewal period is set to 24 hours.
Now, generate a token:
$ curl --header "X-Vault-Token: ..." --request POST \
http://127.0.0.1:8200/v1/auth/token/create/zabbix | jq
{
...
"auth": {
"client_token": "a59c0d41-8df7-ba8e-477e-9bfb394f28a0",
"accessor": "c2023006-ce8d-532b-136f-330223ccf464",
"policies": [
"default"
],
"metadata": null,
"lease_duration": 86400,
"renewable": true,
"entity_id": ""
}
$ curl --header "X-Vault-Token: ..." --request POST \ http://127.0.0.1:8200/v1/auth/token/create/zabbix | jq{ ... "auth": { "client_token": "a59c0d41-8df7-ba8e-477e-9bfb394f28a0", "accessor": "c2023006-ce8d-532b-136f-330223ccf464", "policies": [ "default" ], "metadata": null, "lease_duration": 86400, "renewable": true, "entity_id": "" }
Generated tokens are renewable indefinitely as long as they are renewed
before the lease duration expires. The token renew command was covered in
Step 2.
»Additional Note: Periodic Tokens with AppRole
It probably makes better sense to create AppRole periodic tokens since we
are talking about long-running apps that need to be able to renew their token
indefinitely.
For more details about AppRole, read the AppRole Pull
Authentication guide.
To create AppRole periodic tokens, create your AppRole role with
period
specified.
Example:
$ vault write auth/approle/role/jenkins policies="jenkins" period="72h"
$ vault write auth/approle/role/jenkins policies="jenkins" period="72h"
Or
$ tee payload.json <<EOF
{
"allowed_policies": [
"jenkins"
],
"period": "72h"
}
EOF
$ curl --header "X-Vault-Token:..." --request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/approle/role/jenkins
$ tee payload.json <<EOF{ "allowed_policies": [ "jenkins" ], "period": "72h"}EOF
$ curl --header "X-Vault-Token:..." --request POST \ --data @payload.json \ http://127.0.0.1:8200/v1/auth/approle/role/jenkins
»Step 5: 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.
»CLI command
The following CLI command requires root token or sudo capability on the
auth/token/create
path.
$ vault token create -orphan
$ vault token create -orphan
»API call using cURL
To create an orphan token, use the auth/token/create-orphan
endpoint:
$ curl --header "X-Vault-Token:..." --request POST \
http://127.0.0.1:8200/v1/auth/token/create-orphan | jq
$ curl --header "X-Vault-Token:..." --request POST \ http://127.0.0.1:8200/v1/auth/token/create-orphan | jq
Also, you can create an orphan token using the auth/token/create
endpoint with
no-parent
parameter set to true.
$ curl --header "X-Vault-Token:..." --request POST \
--data '{ "no_parent": true }' \
http://127.0.0.1:8200/v1/auth/token/create | jq
$ curl --header "X-Vault-Token:..." --request POST \ --data '{ "no_parent": true }' \ http://127.0.0.1:8200/v1/auth/token/create | jq
NOTE: The auth/token/create
endpoint requires root token or
sudo capability to create an orphan token while
auth/token/create-orphan
endpoint does not.
»Step 6: Revoke tokens and leases
Revoking a token and all its children.
»CLI command
To revoke a specific token:
$ vault token revoke <TOKEN>
$ vault token revoke <TOKEN>
To revoke all leases under a specific path:
$ vault lease revoke -prefix <PATH>
$ vault lease revoke -prefix <PATH>
Example:
$ vault token revoke eeaf890e-4b0f-a687-4190-c75b1d6d70bc
$ vault lease revoke -prefix database/creds
$ vault lease revoke -prefix auth/token/create
$ vault token revoke -accessor 2b2b5b83-7f22-fecd-03f0-4e25bf64da11
$ vault token revoke eeaf890e-4b0f-a687-4190-c75b1d6d70bc
$ vault lease revoke -prefix database/creds
$ vault lease revoke -prefix auth/token/create
$ vault token revoke -accessor 2b2b5b83-7f22-fecd-03f0-4e25bf64da11
»API call using cURL
To revoke a specific token, call /auth/token/revoke
endpoint. If you want to revoke tokens/secrets under a specific path, call /sys/leases/revoke-prefix/<PATH>
.
Example:
$ curl --header "X-Vault-Token:..." --request POST \
--data '{ "token": "eeaf890e-4b0f-a687-4190-c75b1d6d70bc" }' \
http://127.0.0.1:8200/v1/auth/token/revoke
$ curl --header "X-Vault-Token:..." --request POST \
http://127.0.0.1:8200/v1/sys/leases/revoke-prefix/database/creds
$ curl --header "X-Vault-Token:..." --request POST \
http://127.0.0.1:8200/v1/sys/leases/revoke-prefix/auth/token/create
$ curl --header "X-Vault-Token: ..." --request POST \
--data '{ "accessor": "2b2b5b83-7f22-fecd-03f0-4e25bf64da11" }' \
http://127.0.0.1:8200/v1/auth/token/revoke-accessor
$ curl --header "X-Vault-Token:..." --request POST \ --data '{ "token": "eeaf890e-4b0f-a687-4190-c75b1d6d70bc" }' \ http://127.0.0.1:8200/v1/auth/token/revoke
$ curl --header "X-Vault-Token:..." --request POST \ http://127.0.0.1:8200/v1/sys/leases/revoke-prefix/database/creds
$ curl --header "X-Vault-Token:..." --request POST \ http://127.0.0.1:8200/v1/sys/leases/revoke-prefix/auth/token/create
$ curl --header "X-Vault-Token: ..." --request POST \ --data '{ "accessor": "2b2b5b83-7f22-fecd-03f0-4e25bf64da11" }' \ http://127.0.0.1:8200/v1/auth/token/revoke-accessor
»Advanced Features
It is important to understand lease configuration to avoid having your
secret leases expire earlier than you expected.
»1. Determine the TTLs specific to the mount
$ vault secrets list
Path Type Accessor Plugin Default TTL Max TTL Force No Cache Replication Behavior Seal Wrap Description
cubbyhole/ cubbyhole cubbyhole_36021b8e n/a n/a n/a false local false per-token private secret storage
database/ database database_e21b9b4f n/a system system false replicated false
identity/ identity identity_035fe03b n/a n/a n/a false replicated false identity store
pki/ pki pki_9ae09eb3 n/a system system false replicated false
secret/ kv kv_2e59ba96 n/a system system false replicated false key/value secret storage
ssh/ ssh ssh_ea06b9bb n/a system system false replicated false
sys/ system system_f5b5ecac n/a n/a n/a false replicated false system endpoints used for control, policy and debugging
transit/ transit transit_07fc2df9 n/a system system false replicated false
$ vault secrets list
Path Type Accessor Plugin Default TTL Max TTL Force No Cache Replication Behavior Seal Wrap Descriptioncubbyhole/ cubbyhole cubbyhole_36021b8e n/a n/a n/a false local false per-token private secret storagedatabase/ database database_e21b9b4f n/a system system false replicated falseidentity/ identity identity_035fe03b n/a n/a n/a false replicated false identity storepki/ pki pki_9ae09eb3 n/a system system false replicated falsesecret/ kv kv_2e59ba96 n/a system system false replicated false key/value secret storagessh/ ssh ssh_ea06b9bb n/a system system false replicated falsesys/ system system_f5b5ecac n/a n/a n/a false replicated false system endpoints used for control, policy and debuggingtransit/ transit transit_07fc2df9 n/a system system false replicated false
Notice the Default TTL and Max TTL columns.
»2. Tune the system TTLs
Override the global defaults by specifying default_lease_ttl
and
max_lease_ttl
to meet your requirements.
Example:
The following example assumes that you have a database secret engine configured.
$ vault write sys/mounts/database/tune default_lease_ttl="8640"
$ vault write sys/mounts/database/tune default_lease_ttl="8640"
Or
$ curl --header "X-Vault-Token:..." --request POST \
--data '{ "max_lease_ttl": 129600}' \
http://127.0.0.1:8200/v1/sys/mounts/database/tune
$ curl --header "X-Vault-Token:..." --request POST \ --data '{ "max_lease_ttl": 129600}' \ http://127.0.0.1:8200/v1/sys/mounts/database/tune
»3. Check the role specific TTLs
Depending on the auth method, there may be more specific TTLs configured (e.g.
roles, groups, users) as you have done so in Step 4.
$ vault read auth/token/roles/zabbix
Key Value
--- -----
allowed_policies [default]
disallowed_policies []
explicit_max_ttl 0
name zabbix
orphan false
path_suffix
period 86400
renewable true
$ vault read auth/token/roles/zabbix
Key Value--- -----allowed_policies [default]disallowed_policies []explicit_max_ttl 0name zabbixorphan falsepath_suffixperiod 86400renewable true
»Next steps
Now that you have learned the lifecycle of tokens and leases, read the AppRole Pull
Authentication guide to learn how to generate
tokens for apps or machines.