open-vault/website/source/guides/lease.html.md
2018-01-17 17:39:21 -08:00

712 lines
20 KiB
Markdown

---
layout: "guides"
page_title: "Tokens and Leases - Guides"
sidebar_current: "guides-lease"
description: |-
Tokens are the core method for authentication within Vault. For every
authentication token and dynamic secret, Vault creates a lease
containing information such as a duration, renewability, and more.
Understanding the lifecycle of lease means understanding the lifecycle of
tokens on some sense.
---
# 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 automatically gets 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 follow:
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
- The [Validation](/guides/dynamic-secrets.html#validation) section of the
[Secret as a Service](/guides/dynamic-secrets.html) guide demonstrated lease
renewal and revocation
- [Tokens documentation](/docs/concepts/tokens.html)
- [Token Auth Backend HTTP API](/api/auth/token/index.html)
- [Lease, Renew, and Revoke](/docs/concepts/lease.html)
## Estimated Time to Complete
10 minutes
## Challenge
Consider the following scenarios:
- Currently, there is no **break glass** procedure available
- Credentials for externals systems (e.g. AWS, MySQL) are shared
- Need a temporal access to database in a specific scenario
## Solution
Vault has built-in support for secret revocation. Vault can revoke not only
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. 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](/intro/getting-started/install.html) guide to install Vault.
Make sure that your Vault server has been [initialized and
unsealed](/intro/getting-started/deploy.html).
## Steps
Tokens are the core methods for authentication within Vault. Tokens can be used
directly or dynamically generated by the auth backends. Regardless, the clients
need valid tokens to interact with Vault.
This guide demonstrates the lifecycle of tokens.
1. [Read token backend configuration](#step1)
2. [Create short-live tokens](#step2)
3. [Create tokens with use limit](#step3)
4. [Periodic tokens](#step4)
5. [Orphan tokens](#step5)
6. [Revoke tokens](#step6)
### <a name="step1"></a>Step 1: Read token backend configuration
When you create leases with no specific TTL values, the default value applies
to the lease.
```shell
vault auth -methods
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
```
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 backend system configuration, call
**`/sys/auth/<METHOD>/tune`** endpoint. See the [Reference Content](#reference)
for more detail.
#### CLI command
Read the default TTL settings for **token** auth backend:
```shell
vault read sys/auth/token/tune
Key Value
--- -----
default_lease_ttl 2764800
force_no_cache false
max_lease_ttl 2764800
```
#### API call using cURL
Before begin, create the following environment variables for your convenience:
- **VAULT_ADDR** is set to your Vault server address
- **VAULT_TOKEN** is set to your Vault token
**Example:**
```plaintext
$ export VAULT_ADDR=http://127.0.0.1:8201
$ export VAULT_TOKEN=0c4d13ba-9f5b-475e-faf2-8f39b28263a5
```
Read the default TTL settings for **token** auth backend:
```plaintext
$ curl -X GET -H "X-Vault-Token: $VAULT_TOKEN" $VAULT_ADDR/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).
### <a name="step2"></a>Step 2: Create short-live tokens
Create a new token with TTL of 30 seconds.
#### CLI command
```shell
$ vault token-create -ttl=30s
Key Value
--- -----
token 7544266f-3ec9-81a6-d504-e258b89de862
token_accessor 59aae2f1-2e97-6ebb-f925-8a97cf5a9942
token_duration 30s
token_renewable true
token_policies [root]
$ 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 [root]
renewable true
ttl 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, yet.
```shell
vault token-renew <TOKEN>
```
If you want to renew and extend the token's TTL, pass the desired extension:
```shell
vault token-renew <TOKEN> <EXTENSION>
```
The extension value can be an integer number of seconds (e.g. 3600) or a string
duration (e.g. "1h").
#### API call using cURL
```plaintext
curl -X POST -H "X-Vault-Token: $VAULT_TOKEN" -d '{"ttl": "30s"}' \
$VAULT_ADDR/v1/auth/token/create | jq
{
...
"auth": {
"client_token": "f7d88963-1aba-64d7-11a0-9282ae7681d0",
"accessor": "c0a40d94-b814-e46f-7e56-ee18fccdf1b6",
"policies": [
"root"
],
"metadata": null,
"lease_duration": 30,
"renewable": true
}
}
```
#### Verification
```plaintext
curl -X GET -H "X-Vault-Token: f7d88963-1aba-64d7-11a0-9282ae7681d0" \
$VAULT_ADDR/v1/auth/token/lookup-self | jq
{
...
"data": {
"accessor": "a54fea3f-6c09-d288-ede5-53288569f988",
"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:
```plaintext
$ curl -X POST -H "X-Vault-Token: $VAULT_TOKEN" $VAULT_ADDR/v1/auth/token/renew/<TOKEN> | jq
$ curl -X POST -H "X-Vault-Token: $VAULT_TOKEN" -d '{"increment": "3600"}' \
$VAULT_ADDR/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 past from
the token's creation time, it gets revoked by Vault. For a long running
processes, this may introduce complexity. In such case, use [periodic tokens](#step4).
### <a name="step3"></a>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 use limit, simply set the number of use when you
create them.
#### CLI command
Create a token with `-use-limit` property argument.
**Example:**
```shell
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]
```
This creates a token with _default_ policy with use limit of 2.
#### Verification
```shell
$ 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
```
First command read the token properties, and then wrote a value to cubbyhole
secret backend. This exhausted the use limit of 2 for this token. Therefore,
the attempt to read the secret from cubbyhole failed.
#### API call using cURL
Set the `num_uses` property in the request payload.
```plaintext
curl -X POST -H "X-Vault-Token: $VAULT_TOKEN" -d '{ "policies": ["default"], "num_uses":2 }' \
$VAULT_ADDR/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 _default_ policy with use limit of 2.
#### Verification
```plaintext
$ curl -X GET -H "X-Vault-Token: d9c2f2e5-6b8a-4021-476c-ebd3f166d668" \
$VAULT_ADDR/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 -X POST -H "X-Vault-Token: d9c2f2e5-6b8a-4021-476c-ebd3f166d668" \
-d '{ "value": "d9c2f2e5-6b8a-4021-476c-ebd3f166d668" }' $VAULT_ADDR/v1/cubbyhole/token
$ curl -X GET -H "X-Vault-Token: d9c2f2e5-6b8a-4021-476c-ebd3f166d668" $VAULT_ADDR/v1/cubbyhole/token | jq
{
"errors": [
"permission denied"
]
}
```
First command read the token properties, and then wrote a value to cubbyhole
secret backend. This exhausted the use limit of 2 for this token. Therefore,
the attempt to read the secret from cubbyhole failed.
### <a name="step4"></a>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, it 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.
2764800) or a string duration (e.g. 72h).
```shell
vault write auth/token/roles/<ROLE_NAME> allowed_policies="<POLICY_NAMES>" period=<RENEWAL_PERIOD>
```
**Example:**
```shell
vault write auth/token/roles/zabbix allowed_policies="zabbix-pol, default" period="24h"
```
Now, generate a token:
```shell
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 zabbix-pol]
```
#### 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.
2764800) or a string duration (e.g. 72h).
**Example:**
```plaintext
$ curl -X POST -H "X-Vault-Token: $VAULT_TOKEN" -d @token-role.json \
$VAULT_ADDR/v1/auth/token/roles/zabbix
$ cat token-role.json
{
"allowed_policies": [
"default",
"zabbix-pol"
],
"period": "24h"
}
```
This creates a token role named `zabbix` with `default` and `zabbix-pol`
policies attached. Also, its renewal period is set to 24 hours.
Now, generate a token:
```plaintext
curl -X POST -H "X-Vault-Token: $VAULT_TOKEN" $VAULT_ADDR/v1/auth/token/create/zabbix | jq
{
...
"auth": {
"client_token": "a59c0d41-8df7-ba8e-477e-9bfb394f28a0",
"accessor": "c2023006-ce8d-532b-136f-330223ccf464",
"policies": [
"default",
"zabbix-pol"
],
"metadata": null,
"lease_duration": 86400,
"renewable": true,
"entity_id": ""
}
```
-> Generated tokens are renewable indefinitely for as long as it gets renewed
before its lease duration expires. The token renew command was covered in
[Step 2](#step2).
#### Periodic Tokens with AppRole
It probably makes better sense to create **AppRole** periodic tokens since we
are talking about long-running apps need to be able to renew its token
indefinitely. To create AppRole periodic tokens, create your AppRole role with
`period` specified.
**Example:**
```plaintext
vault write auth/approle/role/jenkins policies="dev-pol,devops-pol" period="72h"
```
Or
```plaintext
$ curl -X POST -H "X-Vault-Token:$VAULT_TOKEN" -d @payload.json \
$VAULT_ADDR/v1/auth/approle/role/jenkins
$ cat payload.json
{
"allowed_policies": [
"dev-pol",
"devops-pol"
],
"period": "72h"
}
```
For more details about AppRole, refer to [Authentication - AppRole guide](/guides/authentication.html).
### <a name="step5"></a>Step 5: Orphan tokens
Root or sudo users have the ability to generate **orphan** tokens. Orphan tokens
are **not** children of their parent; therefore, it does not expire when their
parent does.
**NOTE:** Orphan tokens still expire when their own max TTL is reached.
#### CLI command
```shell
vault token-create -orphan
```
#### API call using cURL
```plaintext
$ curl -X POST -H "X-Vault-Token:$VAULT_TOKEN" -d '{ "no_parent": true }' \
$VAULT_ADDR/v1/auth/token/create-orphan | jq
```
### <a name="step6"></a>Step 6: Revoke tokens
Revoking a token and all its children.
#### CLI command
To revoke a specific token:
```shell
vault token-revoke <TOKEN>
```
To revoke all tokens under a specific path:
```shell
vault token-revoke -prefix <PATH>
```
**Example:**
```shell
# Revoke a specific token
$ vault token-revoke eeaf890e-4b0f-a687-4190-c75b1d6d70bc
# Revoke all secrets for database auth backend
$ vault token-revoke -prefix database/creds
# Revoke all tokens
$ vault token-revoke -prefix auth/token/create
```
#### 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:**
```shell
# Revoke a specific token
$ curl -X POST -H "X-Vault-Token:$VAULT_TOKEN" -d '{ "token": "eeaf890e-4b0f-a687-4190-c75b1d6d70bc" }' \
$VAULT_ADDR/v1/auth/token/revoke
# Revoke all secrets for database auth backend
$ curl -X POST -H "X-Vault-Token:$VAULT_TOKEN" $VAULT_ADDR/v1/sys/leases/revoke-prefix/database/creds
# Revoke all tokens
$ curl -X POST -H "X-Vault-Token:$VAULT_TOKEN" $VAULT_ADDR/v1/sys/leases/revoke-prefix/auth/token/create
```
## Advanced Features
It is important to understand the lease configuration to avoid having your
secret leases expiring earlier than you expected.
#### 1. Determine the TTLs specific to the mount
```shell
$ vault mounts
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
```
#### 2. Tune the system TTLs
Override the global defaults by specifying `default_lease_ttl` and
`max_lease_ttl` to meet your requirements.
**Example:**
```shell
$ vault write sys/mounts/database/tune default_lease_ttl="8640"
```
Or
```plaintext
$ curl -X POST -H "X-Vault-Token:$VAULT_TOKEN" -d `{ "max_lease_ttl": 129600}`\
$VAULT_ADDR/v1/sys/mounts/database/tune
```
#### 3. Check the role specific TTLs
Depending on the backend, there may be more specific TTLs configured (e.g.
roles, groups, users) as you have done so in [Step 4](#step4).
```shell
$ vault read auth/token/roles/zabbix
Key Value
--- -----
allowed_policies [default zabbix-pol]
disallowed_policies []
explicit_max_ttl 0
name zabbix
orphan false
path_suffix
period 86400
renewable true
```
## Next steps