Token management

8min
|
Vault

The Tokens tutorial demonstrated the lifecycle of Vault tokens. Remember that Vault persists the service tokens in the storage backend until they expire and Vault revokes them. Depending on the auth method, the generated service token varies in its size due to the amount of metadata attached to it. To avoid unused tokens from overtaking the storage memory, set an explicit token time-to-live (TTL) so that Vault will automatically revoke expired tokens.

Lab setup

To perform the tasks described in this tutorial, you need to have a Vault environment.

Refer to the Getting Started tutorial to install Vault.

Start a Vault dev server with root as the root token.
```
$ vault server -dev -dev-root-token-id root
```
Insecure operation
Do not run a Vault dev server in production. This approach is only used here to simplify the unsealing process for this demonstration.
Export an environment variable for the vault CLI to address the Vault server.
```
$ export VAULT_ADDR=http://127.0.0.1:8200
```

$ vault login root

Success! You are now authenticated. The token information displayed below
is already stored in the token helper. You do NOT need to run "vault login"
again. Future Vault requests will automatically use this token.

Key                  Value
---                  -----
token                root
token_accessor       n9CYvD0GK3iV6nwAOZQAy9Md
token_duration       ∞
token_renewable      false
token_policies       ["root"]
identity_policies    []
policies             ["root"]

The Vault server is ready.

Note

If you do not have access to an HCP Vault Dedicated cluster, visit the Create a Vault Cluster on HCP tutorial.

Launch the HCP Portal and login.
Click Vault in the left navigation pane.
In the Vault clusters pane, click vault-cluster.
Under Cluster URLs, click Public Cluster URL.
In a terminal, set the VAULT_ADDR environment variable to the copied address.
```
$ export VAULT_ADDR=<Public_Cluster_URL>
```
Return to the Overview page and click Generate token.
Within a few moments, a new token will be generated.
Copy the Admin Token.
Return to the terminal and set the VAULT_TOKEN environment variable.
```
$ export VAULT_TOKEN=<token>
```
Set the VAULT_NAMESPACE environment variable to admin.
```
$ export VAULT_NAMESPACE=admin
```
The admin namespace is the top-level namespace automatically created by HCP Vault. All CLI operations default to use the namespace defined in this environment variable.

Type vault status to verify your connectivity to the Vault cluster.

$ vault status

Key                      Value
---                      -----
Recovery Seal Type       shamir
Initialized              true
Sealed                   false
Total Recovery Shares    1
Threshold                1
Version                  1.12.3+ent
Build Date               2023-02-03T12:10:29Z
Storage Type             raft
...snipped...

The Vault Dedicated server is ready.

Configure the token TTL

When you create tokens or leases with no specific TTL values, the default value applies to them.

Create a token with default policy.

$ vault token create -policy=default

Key                  Value
---                  -----
token                hvs.CAESIPTd9dl2cePaceCI8SLKjD-mEq8pVC4vy730D7m9jImjGh4KHGh2cy45Y2pyUU5rSTB4Y3hpeno0aVJEZld3U1E
token_accessor       nE3v6ijndqozPlL5WPvY1LIq
token_duration       768h
token_renewable      true
token_policies       ["default"]
identity_policies    []
policies             ["default"]

Notice that the token TTL (token_duration) is 768 hours although you did not provide the TTL value.

Display the token auth method settings.
```
$ vault auth list -detailed

Path      Plugin    Accessor               Default TTL    Max TTL    Token Type    ...
----      ------    --------               -----------    -------    ----------
token/    token     auth_token_03fa2d1f    system         system     default-service ...
```
The token auth method is the core method of authentication with Vault; therefore, Vault enables it by default while other auth methods must be enabled explicitly. Notice that the token_type is default-service.
Note
The Default TTL and Max TTL of the token auth method is set to system.
Read the default TTL settings for token auth method.
```
$ vault read sys/auth/token/tune

Key                  Value
---                  -----
default_lease_ttl    768h
description          token based credentials
force_no_cache       false
max_lease_ttl        768h
token_type           default-service
```
The default token TTL (default_lease_ttl) and the max TTL (max_lease_ttl) is set to 32 days (768 hours). This implies that the tokens are valid for 32 days from its creation whether an app is using the token or not.
Tip
The Tokens tutorial demonstrated various parameters to control the token lifecycle; however, users often neglect to specify the token TTL.
You can override the default TTL on the token auth method itself so that Vault will revoke expired token in a reasonable amount of time.

Set the default TTL to 8 hours and max TTL to 30 days (720 hours).

$ vault write sys/auth/token/tune default_lease_ttl=8h max_lease_ttl=720h
Success! Data written to: sys/auth/token/tune

Read the configuration to verify.

$ vault read sys/auth/token/tune

Key                  Value
---                  -----
default_lease_ttl    8h
description          token based credentials
force_no_cache       false
max_lease_ttl        720h
token_type           default-service

Verification

Create a new token without specifying its TTL.

$  vault token create -policy=default

Key                  Value
---                  -----
token                hvs.CAESIEGiDhSts4rDwJQw4Twre1IJACXB5h288PWJVgZFMSbcGh4KHGh2cy5NZ09icUxqdmZnYU1wd1VJZGE5M0pDV0k
token_accessor       RtW8rWhB7trpfyfm9IC8Fow1
token_duration       8h
token_renewable      true
token_policies       ["default"]
identity_policies    []
policies             ["default"]

Tip

Tune any of the auth method configurations using the /sys/auth/<METHOD>/tune endpoint to override the system defaults.

Create a token with default policy.

$ vault token create -policy=default

Key                  Value
---                  -----
token                hvs.CAESII3jTqKyWx8RJMPpzm9qEr_NypWV8K-66ftFSyXW1d-PGigKImh2cy43ZUx5UnVJcncwMTBSZHJ0OUJ2RVZ0MGYubUVuSTUQm44B
token_accessor       P2kBi9NODldC3SQUl07P5Zr4.mEnI5
token_duration       1h
token_renewable      true
token_policies       ["default"]
identity_policies    []
policies             ["default"]

Notice that the token TTL (token_duration) is 1 hour although you did not provide the TTL value.

Display the token auth method settings.
```
$ vault auth list -detailed

Path      Plugin    Accessor               Default TTL    Max TTL    Token Type    ...
----      ------    --------               -----------    -------    ----------
token/    token     auth_token_03fa2d1f    system         system     default       ...
```
The token auth method is the core method of authentication with Vault; therefore, Vault enables it by default while other auth methods must be enabled explicitly. Notice that the token_type is default.
Note
The Default TTL and Max TTL of the token auth method is set to system.
Read the default TTL settings for token auth method.
```
$ vault read sys/auth/token/tune

Key                  Value
---                  -----
default_lease_ttl    1h
description          token based credentials
force_no_cache       false
max_lease_ttl        768h
token_type           default
```
The default token TTL (default_lease_ttl) is set to 1h and the max TTL (max_lease_ttl) is set to 32 days (768 hours). This implies that the tokens are valid for 1 hour from its creation whether an app is using the token or not.
Note
HCP Vault Dedicated users have access to a limited number of sys/ endpoints. The sys/auth/token/tune endpoint cannot be used to alter the default TTL for Vault Dedicated. Refer to the Vault Dedicated Security Overview documentation for more information.
The Tokens tutorial demonstrated various parameters to control the token lifecycle; however, users often neglect to specify the token TTL. You can override the default TTL on an individual token so that Vault will revoke expired token in the desired amount of time.

Create a new token setting its TTL to 8 hours.

$  vault token create -ttl=8h

Key                  Value
---                  -----
token                hvs.CAESIByX0uCcbIZhIJBIEHErHKvzHS4dbPMyvPuoPyRj43e5GigKImh2cy5mVjVUd25KU284aUl1UU11RzVyOU9KWk4ubUVuSTUQqI4B
token_accessor       5TmzE2BltMlMrG8J6lTuKHh5.mEnI5
token_duration       8h
token_renewable      true
token_policies       ["default" "hcp-root"]
identity_policies    []
policies             ["default" "hcp-root"]

Get the token count

If the token TTL is set reasonably, Vault should not be storing many unused tokens.

Refer to the Vault Usage Metrics tutorial which demonstrates the Usage Metrics dashboard.

Get the service token counts.

$ vault read sys/internal/counters/tokens

Example output:

Key         Value
---         -----
counters    map[service_tokens:map[total:3]]

Get the service token counts using the sys/internal/counters/tokens endpoint. (NOTE: This example uses jq to process the JSON output for readability.)

$ curl --header "X-Vault-Token:root" \
       $VAULT_ADDR/v1/sys/internal/counters/tokens | jq .data

Example output:

{
  "counters": {
    "service_tokens": {
      "total": 3
    }
  }
}

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
    $VAULT_ADDR/v1/sys/internal/counters/tokens | jq .data

Example output:

{
  "counters": {
    "service_tokens": {
      "total": 3
    }
  }
}

The example output shows that there are 5 service tokens. In reality, you may have hundreds of app instances connecting to Vault. Then it becomes more important to know how many tokens exist in the Vault's storage backend.

Note

Remember that Vault does not persist batch tokens. Therefore, the sys/internal/counters/tokens endpoint returns the number of service tokens in Vault.

Reference materials

Batch tokens

Next Collection

ADP