HashiCorp Developer AI Private beta now available Sign up today
Vault
Authentication

Tokens

  • 35min
  • |
  • Vault
  • Interactive

Deployment

What are tokens

Tokens are the core method for authenticate and validate Vault clients; therefore, nearly all requests to Vault must be accompanied by a token. Vault clients authenticate with Vault using a configured auth method (Okta, Kubernetes, etc.). Upon successful authentication, Vault generates a token managed by the token backend and returns it to the client.

Client authentication workflow

The token auth method is built-in and is at the core of client authentication. A client can authenticate with Vault through the token auth method. For example, a Vault admin logs in with Vault via token auth method using the initial root token (or admin token if you are running HCP Vault Dedicated) so that the admin can configure other auth methods.

Authenticate with token auth

Note

It is generally considered a best practice not to persist root tokens. Use the root token only for just enough initial setup. Once you enabled an auth method with appropriate policies allowing Vault admins to log in and perform operational tasks, the admins should use the auth method to authenticate instead of using the root token.

Token types

There are two types of Vault tokens: service token and batch token. Vault persists the service tokens in its storage backend. You can renew a service token or revoke it as necessary. On the other hand, Vault does not persist the batch tokens. Batch tokens are encrypted binary large objects (blobs) that carry enough information to perform Vault actions. Therefore, batch tokens are extremely lightweight and scalable; however, they lack most of the flexibility and features of service tokens.

In addition, there is a recovery token which is a special token used when Vault is running in recovery mode. To learn more, read the Operate Vault in Recovery Mode tutorial.

Token prefix

Tokens have a prefix that indicates their type. As of Vault 1.10, the token format has changed. The following table lists the prefix differences.

Token TypeVault 1.9.x or earlierVault 1.10 and later
Service tokenss.hvs.
Batch tokensb.hvb.
Recovery tokensr.hvr.

When you upgrade your existing Vault cluster to Vault 1.10 or later, the tokens generated prior to Vault 1.10 will still work if they have not expired.

This tutorial focuses on the service tokens. Read the batch tokens tutorial to learn the usage of batch tokens.

Service token lifecycle

Every non-root token has a time-to-live (TTL). When a token expires, Vault automatically revokes it. If you create a new token, the token you used to create the token becomes the parent token. Once the parent token expires, so do all its children regardless of their own TTLs.

Suppose a hierarchy exists with respective TTL as follows:

    hvs.b519c6aa... (1h)
    |___ hvs.6a2cf3e7... (4h)
    |___ hvs.1d3fd4b2... (2h)
          |___ hvs.794b6f2f... (3h)

In this scenario, the token hvs.1d3fd4b2.. will expire in two hours. Although its child token (hvs.794b6f2f...) has TTL of three hours, Vault will revoke the child token when its parent expires.

When the top-level token (hvs.b519c6aa...) expires, Vault will revoke all tokens under the tree (hvs.6a2cf3e7..., hvs.1d3fd4b2..., and hvs.794b6f2f...) regardless of their TTL.

TTL and max TTL

If the token is renewable, you can use vault token renew command to extend the token's TTL before it expires. You can repeatedly renew a token until it reaches its maximum TTL.

For example, if a token's TTL is 30 minutes and the maximum TTL is 24 hours, you can renew the token before reaching the 30 minutes. You can renew the token multiple times if you are using it. However, once the token reaches the 24 hours of its first creation, you can no longer renew the token.

Important

If you do not explicitly set the token's TTL or maximum TTL, it takes the system max TTL which is 32 days by default. (You can change the system default in the Vault server configuration file.) This means that Vault stores the token in its storage backend for 32 days even if you are not using it.

What you are going to learn

This tutorial explores the lifecycle of service tokens.

Prerequisites

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

Launch Terminal

This tutorial includes a free interactive command-line lab that lets you follow along on actual cloud infrastructure.

Lab setup

  1. Open a terminal and start a Vault dev server with root as the root token.

    $ vault server -dev -dev-root-token-id root

    The Vault dev server defaults to running at 127.0.0.1:8200. The server is initialized and unsealed.

    Insecure operation

    Do not run a Vault dev server in production. This approach starts a Vault server with an in-memory database and runs in an insecure way.

  2. Export an environment variable for the vault CLI to address the Vault server.

    $ export VAULT_ADDR=http://127.0.0.1:8200

  3. Export an environment variable for the vault CLI to authenticate with the Vault server.

    $ export VAULT_TOKEN=root

    Note

    For these tasks, you can use Vault's root token. However, it is recommended that root tokens are only used for enough initial setup or in emergencies. As a best practice, use an authentication method or token that meets the policy requirements.

The Vault server is ready.

Tokens with use limit

In addition to TTL and max TTL, you can set the number of uses for tokens. The tokens with a use limit 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.

  1. To view optional parameters to create tokens, run the command with -help flag.

    $ vault token create -help

Usage: vault token create [options]

  Creates a new token that can be used for authentication. This token will be
  created as a child of the currently authenticated token. The generated token
  will inherit all policies and permissions of the currently authenticated
  token unless you explicitly define a subset list policies to assign to the
  token.

  A ttl can also be associated with the token. If a ttl is not associated
  with the token, then it cannot be renewed. If a ttl is associated with
  the token, it will expire after that amount of time unless it is renewed.

  Metadata associated with the token (specified with "-metadata") is written
  to the audit log when the token is used.

  If a role is specified, the role may override parameters specified here.

    There are a number of parameters you can set.

  2. Create a token with a TTL of 1 hour and a use limit of 2. Attach the default policy.

    $ vault token create -ttl=1h -use-limit=2 -policy=default

Key                  Value
---                  -----
token                hvs.CAESIJRM-T1q5lEjIWux1Tjx-VGqAYJdd4FZtbp1wpD5Ym9pGh4KHGh2cy5TSjRndGoxaU44NzNscm5MSlRLQXZ0ZGg
token_accessor       GMAlk9ZNLGOCuTrOEIAooJG3
token_duration       1h
token_renewable      true
token_policies       ["default"]
identity_policies    []
policies             ["default"]

Verification

  1. Store the generated token in an environment variable, USE_LIMIT_TOKEN.

    Example:

    $ export USE_LIMIT_TOKEN="hvs.CAESIJRM-T1q5lEjIWux1Tjx-VGqAYJdd4FZtbp1wpD5Ym9pGh4KHGh2cy5TSjRndGoxaU44NzNscm5MSlRLQXZ0ZGg"

  2. Set the VAULT_TOKEN value to the token you just generated, and invoke any CLI command.

    $ VAULT_TOKEN=$USE_LIMIT_TOKEN vault token lookup

    Example output:

    Key                 Value
---                 -----
accessor            GMAlk9ZNLGOCuTrOEIAooJG3
creation_time       1646691009
creation_ttl        1h
display_name        token
entity_id           n/a
expire_time         2022-03-07T15:10:09.115115-08:00
explicit_max_ttl    0s
id                  hvs.CAESIJRM-T1q5lEjIWux1Tjx-VGqAYJdd4FZtbp1wpD5Ym9pGh4KHGh2cy5TSjRndGoxaU44NzNscm5MSlRLQXZ0ZGg
issue_time          2022-03-07T14:10:09.115118-08:00
meta                <nil>
num_uses            1
orphan              false
path                auth/token/create
policies            [default]
renewable           true
ttl                 58m14s
type                service

    Notice that the num_uses is now 1.

  3. Run another CLI command using the token.

    $ VAULT_TOKEN=$USE_LIMIT_TOKEN vault write cubbyhole/token value=1234567890
Success! Data written to: cubbyhole/token

  4. Try to read the value now using the same token.

    $ VAULT_TOKEN=$USE_LIMIT_TOKEN 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.

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 renew service tokens to learn more about the period and the maximum TTL.

  1. Create a token with 24 hours period.

    $ vault token create -policy="default" -period=24h

Key                  Value
---                  -----
token                hvs.CAESIIG_PILmULFYOsEyWHxkZ2mF2a8VPKNLE8eHqd4autYGGh4KHGh2cy5aeTY0NFNSaUp3ZnpWbDF1RUNjUkNTZEg
token_accessor       kfhjoayUCHo1yjdbT0YWvlJ1
token_duration       24h
token_renewable      true
token_policies       ["default"]
identity_policies    []
policies             ["default"]

  2. Generate a periodic token again and store the token value in a periodic_token.txt file.

    $ vault token create -policy="default" -period=24h -format=json \
   | jq -r ".auth.client_token" > periodic_token.txt

  3. Display the generated token's metadata.

    $ vault token lookup $(cat periodic_token.txt)

    Example output:

    Key                 Value
---                 -----
accessor            kfhjoayUCHo1yjdbT0YWvlJ1
creation_time       1646692678
creation_ttl        24h
display_name        token
entity_id           n/a
expire_time         2022-03-08T14:37:58.619594-08:00
explicit_max_ttl    0s
id                  hvs.CAESIIG_PILmULFYOsEyWHxkZ2mF2a8VPKNLE8eHqd4autYGGh4KHGh2cy5aeTY0NFNSaUp3ZnpWbDF1RUNjUkNTZEg
issue_time          2022-03-07T14:37:58.619605-08:00
meta                <nil>
num_uses            0
orphan              false
path                auth/token/create
period              24h
policies            [default]
renewable           true
ttl                 23h58m20s
type                service

    You can renew the generated token indefinitely for as long as it does not expire. If you do not renew, the token expires after 24 hours.

    Token Renewal

    Jump to the Renew service tokens section to learn how to renew the generated token.

Short-lived tokens

Create a new service token with a TTL of 60 seconds which means that the token gets automatically revoked after 60 seconds.

  1. Create a token with a TTL of 60 seconds, and store the generated token value in a short-lived_token.txt file.

    $ vault token create -ttl=60s -format=json \
   | jq -r ".auth.client_token" > short-lived_token.txt

  2. Lookup the generated token's metadata.

    $ vault token lookup $(cat short-lived_token.txt)

    Example output:

    Key                 Value
---                 -----
accessor            2jiF5migalnLOmlMkeFNhMCl
creation_time       1646694149
creation_ttl        1m
display_name        token
entity_id           n/a
expire_time         2022-03-07T15:03:29.91061-08:00
explicit_max_ttl    0s
id                  hvs.Dq0oT4q4QrUiBagHlYCaPoWn
issue_time          2022-03-07T15:02:29.910614-08: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 38 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.

Orphan tokens still expire when their own max TTL is reached.

Root privilege

A user must use a root token or token with sudo capability on the auth/token/create endpoint to generate an orphan token via CLI.

  1. Generate an orphan token, and store the generated token value in a orphan_token.txt file.

    $ vault token create -orphan -format=json \
   | jq -r ".auth.client_token" > orphan_token.txt

  2. Lookup the generated token's metadata.

    $ vault token lookup $(cat orphan_token.txt)

    Example output:

    Key                 Value
---                 -----
accessor            KiN7wpFjSaAJQWWnoz2lwo0g
creation_time       1646695005
creation_ttl        0s
display_name        token
entity_id           n/a
expire_time         <nil>
explicit_max_ttl    0s
id                  hvs.YUteYoajMNxJ3u4u8I3znXLe
issue_time          2022-03-07T15:16:45.704173-08:00
meta                <nil>
num_uses            0
orphan              true
path                auth/token/create
policies            [root]
renewable           false
ttl                 0s
type                service

Validation

The revoke service tokens section tests the lifecycle of orphan tokens.

Token role

Instead of passing a number of parameters, you can create a role with a set of parameter values set.

  1. Create a token role named zabbix.

    $ vault write auth/token/roles/zabbix \
    allowed_policies="policy1, policy2, policy3" \
    orphan=true \
    period=8h

  2. Create a token for zabbix role.

    $ vault token create -role=zabbix

    Example output:

    Key                  Value
---                  -----
token                hvs.CAESINGbJtl4chQaJ2fH0ftOsYwr5IGTimfAubxs_Fjxz_OSGh4KHGh2cy5GSjQzaVU5bjFTR1ZoaVhnSmVlSUZFbDE
token_accessor       vqKXT2A8SUltDgTD0vUPCDcz
token_duration       8h
token_renewable      true
token_policies       ["default" "policy1" "policy2" "policy3"]
identity_policies    []
policies             ["default" "policy1" "policy2" "policy3"]

    The generated token is valid for 8 hours and it is renewable, and multiple policies are attached.

Renew service tokens

You can renew the service token's TTL as long as it has not expired.

  1. Create a token and save its value in a file, test_token.txt.

    $ vault token create -ttl=45 -explicit-max-ttl=120 -policy=default -format=json \
    | jq -r ".auth.client_token" > test_token.txt

    The generated token has a TTL of 45 seconds, and max TTL of 2 minutes (120 seconds).

  2. Renew the token's TTL before the token expires.

    $ vault token renew $(cat test_token.txt)

    Example output:

    Key                  Value
---                  -----
token                hvs.CAESIJhnPJRhqeKian6_ZOcyFW362xgUG9wGkC2f2YYDlxFoGh4KHGh2cy5lN0FGUEF6a0R6d2RmenRNVTNtSnJOQms
token_accessor       Pd0QJMV6NcRz3ZFZOecOQqIh
token_duration       45s
token_renewable      true
token_policies       ["default"]
identity_policies    []
policies             ["default"]

  3. Renew and extend the token's TTL to 60 seconds.

    $ vault token renew -increment=60 $(cat test_token.txt)

    Example output:

    Key                  Value
---                  -----
token                hvs.CAESIJhnPJRhqeKian6_ZOcyFW362xgUG9wGkC2f2YYDlxFoGh4KHGh2cy5lN0FGUEF6a0R6d2RmenRNVTNtSnJOQms
token_accessor       Pd0QJMV6NcRz3ZFZOecOQqIh
token_duration       1m
token_renewable      true
token_policies       ["default"]
identity_policies    []
policies             ["default"]

    Notice that the token TTL (token_duration) is now 1 minute instead of 45 seconds.

Because the explicit max TTL is set to 2 minutes, you will not be able to renew the token after 2 minutes.

As time passes, Vault returns a message such as TTL of "26s" exceeded the effective max_ttl of "10s"; TTL value is capped accordingly to indicate that the token TTL cannot exceed 2 minutes from its creation time. Eventually, the token expires and Vault automatically revokes it. Once the token expires, the renew command returns token not found message.

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.

You can revoke service tokens using the vault token revoke command or the auth/token/revoke API endpoint.

In this section, you are going to create tokens with the following hierarchy and inspect the token lifecycle.

 parent_token (1 minute)
    |___ child_token (3 minutes)
    |___ orphan_token (3 minutes)

  1. Create a test policy.

    $ vault policy write test -<<EOF
path "auth/token/create" {
   capabilities = ["create", "read", "update", "delete", "list", "sudo"]
}
EOF

    If you are not familiar with policies, complete the policies tutorial.

  2. Create a token and save its value in a file, parent_token.txt.

    $ vault token create -ttl=60 -policy=test -format=json \
    | jq -r ".auth.client_token" > parent_token.txt

    The generated token has a TTL of 1 minute (60 seconds).

  3. Create a token using the parent token and save its value in a file, child_token.txt.

    $ VAULT_TOKEN=$(cat parent_token.txt) \
   vault token create -ttl=180 -policy=default -format=json \
    | jq -r ".auth.client_token" > child_token.txt

    The generated token has a TTL of 3 minute (180 seconds) while its parent token's TTL is 1 minute.

  4. Create an orphan token using the parent token and save its value in a file, orphan_token.txt.

    $ VAULT_TOKEN=$(cat parent_token.txt) \
   vault token create -orphan -ttl=180 -policy=default -format=json \
    | jq -r ".auth.client_token" > orphan_token.txt

    The generated token is an orphan token with a TTL of 3 minute (180 seconds).

  5. Revoke the parent token.

    $ vault token revoke $(cat parent_token.txt)
Success! Revoked token (if it existed)

  6. Verify that the token no longer exists by looking it up.

    $ vault token lookup $(cat parent_token.txt)

    Vault returns an error message.

    Error looking up token: Error making API request.

URL: POST http://127.0.0.1:8200/v1/auth/token/lookup
Code: 403. Errors:

* bad token

  7. Look up the child token.

    $ vault token lookup $(cat child_token.txt)

    Vault returns the bad token error because Vault revoked the child token along with its parent token.

  8. Look up the orphan token.

    $ vault token lookup $(cat orphan_token.txt)

    Because each orphan token is the root of its own token tree, it exists until it expires. Therefore, the command displays the detail information about the orphan token.

    Tip

    Instead of revoking using a token value, revoke tokens with a token accessor using the -accessor flag.

Apply token types

You learned how you can set the token's lifecycle. The next step is to apply this to generate 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.

Use the AppRole auth method to demonstrate this.

  1. Enable the approle auth method.

    $ vault auth enable approle
Success! Enabled approle auth method at: approle/

  2. Create a role for your app specifying that the generated token type is periodic and expires after 24 hours if not renewed.

    $ vault write auth/approle/role/jenkins policies="jenkins" period="24h"
Success! Data written to: auth/approle/role/jenkins

    This example defines a role named, "jenkins". The tokens generated for this role will be a periodic token with jenkins policy attached.

Verification

Note

If you are not familiar with the AppRole auth method, read the AppRole Pull Authentication tutorial.

  1. Retrieve the RoleID for the jenkins role and save it in a file, role_id.txt.

    $ vault read -format=json auth/approle/role/jenkins/role-id \
    | jq -r ".data.role_id" > role_id.txt

  2. Generate a SecretID for the jenkins role and save it in a file, secret_id.txt.

    $ vault write -f -format=json auth/approle/role/jenkins/secret-id \
    | jq -r ".data.secret_id" > secret_id.txt

  3. Authenticate with Vault using the generated role_id and secret_id.

    $ vault write auth/approle/login role_id=$(cat role_id.txt) \
     secret_id=$(cat secret_id.txt)

    Example output:

    Key                     Value
---                     -----
token                   hvs.CAESINkhQovozcMjgFICYH4JrRfr9wIVIoYMzPirvFRuKjigGh4KHGh2cy43TVhCaTY3c3dvNXliNjNnN1NPNWVyZjk
token_accessor          RaASz9meQMF1bO1h3plDqt18
token_duration          24h
token_renewable         true
token_policies          ["default" "jenkins"]
identity_policies       []
policies                ["default" "jenkins"]
token_meta_role_name    jenkins

  4. View the token details.

    $ vault token lookup <returned_token>

    Example:

    $ vault token lookup hvs.CAESINkhQovozcMjgFICYH4JrRfr9wIVIoYMzPirvFRuKjigGh4KHGh2cy43TVhCaTY3c3dvNXliNjNnN1NPNWVyZjk

Key                 Value
---                 -----
accessor            RaASz9meQMF1bO1h3plDqt18
creation_time       1646696969
creation_ttl        24h
display_name        approle
entity_id           99eb72ff-9c0f-986e-0197-ceee17848a78
expire_time         2022-03-08T15:49:29.196039-08:00
explicit_max_ttl    0s
id                  hvs.CAESINkhQovozcMjgFICYH4JrRfr9wIVIoYMzPirvFRuKjigGh4KHGh2cy43TVhCaTY3c3dvNXliNjNnN1NPNWVyZjk
issue_time          2022-03-07T15:49:29.196043-08:00
meta                map[role_name:jenkins]
num_uses            0
orphan              true
path                auth/approle/login
period              24h
policies            [default jenkins]
renewable           true
ttl                 23h58m31s
type                service

    The output shows the period of 24 hours, and the jenkins policy is attached.

Clean up

If you wish to clean up your environment after completing the tutorial, follow the steps in this section.

  1. Unset the VAULT_TOKEN environment variable.

    $ unset VAULT_TOKEN

  2. Unset the VAULT_ADDR environment variable.

    $ unset VAULT_ADDR

  3. Delete the files used to test tokens.

    $ rm *_token.txt role_id.txt secret_id.txt payload.json renew_payload.json

  4. If you are running Vault locally in -dev mode, you can stop the Vault dev server by pressing Ctrl+C where the server is running. Or, execute the following command.

    $ pgrep -f vault | xargs kill

Next steps

This tutorial walked through the lifecycle of service tokens. You learned how to generate a token using the vault token create command or the /auth/token/create endpoint. Then, you learned how to apply the desired token lifecycle when you configure an auth method in the Apply token type section.

Integrating your application to read or write secrets to Vault may require:

  • Authenticate with Vault using an auth method
  • Maintain the token
  • Renew or revoke the token if necessary

Vault Agent can help to simplify the introduction of Vault to your applications. The App Integration tutorials introduce different approaches.

But first, go through the Batch tokens tutorial to understand the difference between the service tokens and batch tokens so that you can decide which token type is best suited for your use case.

Reference materials

Collection Overview

Authentication

 Next

OIDC auth method

This tutorial also appears in:

  • 3 tutorials
    Vault tokens
    Tokens are the core method for authentication within Vault.
    • Vault

Deployment