Introduction to tokens

Vault issues a token to a client upon successful authentication. A token validates a Vault clients access to Vault and what actions the client can perform. Most actions in Vault require a token. This tutorial provides context for how and why tokens are used in Vault. In later tutorials, you will create tokens using the Vault CLI, HTTP API, UI, and Terraform.

Scenario

HashiCups is preparing for their Vault proof-of-concept (POC) and need to understand how clients, both human and machine, receive authorization to perform operations in a Vault cluster. Alice from the architect team and Oliver from operations meet with HashiCorp to understand the authentication and authorization process for Vault.

HashiCorp will show several important concepts using the Vault CLI. In later tutorials, you will learn to use a number of different interfaces to interact with Vault.

Alice has designed the Vault POC to use the Vault userpass auth method to allow teams to authenticate to Vault with a username and password. Workloads will use the kubernetes auth method to allow resources such as pods managed by Kubernetes to authenticate.

What is a Vault token

Before a client, either a human or machine, can perform an operation in Vault that client must authenticate to Vault. Upon successful authentication, Vault issues a token from the Vault auth method used to authenticate with the Vault cluster.

When you start a Vault cluster, like you did in the set up Vault tutorial, it starts with a root token (or an admin token for HCP Vault Dedicated). This initial token provides full access to Vault, similar to the root user in Linux or domain administrator in Active Directory. The token auth method generates the token and attaches the root policy to the token.

Root token use needs to be extremely guarded in production environments because it provides full access to the Vault server. Only use the root token for initial configuration of Vault, or for emergency access.

How Vault issues tokens

Alice has selected the userpass and kubernetes auth methods for the HashiCups POC. The userpass auth method acts similar to an identity provider, storing a list of usernames, passwords, and policies assigned to the username. The kubernetes auth method allows Vault to validate a workload managed by Kubernetes against the Kubernetes API.

A client will authenticate against an auth method, and upon successful authentication, Vault will issue a token to the client.

The basic authentication flow is:

1. A client attempts to authenticate with Vault.
2. Vault verifies the identity with a trusted provider. For the HashiCups POC this would be Vault itself for userpass auth method or the Kubernetes API for the kubernetes auth method.
3. The identity provider validates the Vault client's identity.
4. Vault returns a token to the client.

Regardless of the auth method used, a client must first authenticate with Vault to receive a token.

Token metadata

Every token includes information about that token. Oliver logs into a Vault dev mode server to learn about the information associated with a root token.

Example:

$ vault login
Token (will be hidden):
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                hvs.zPuyktykA...example...ewUEnIRVaKoBzs2
token_accessor       CqT9Qr54X67om6UDBoJ4G1wH
token_duration       ∞
token_renewable      false
token_policies       ["root"]
identity_policies    []
policies             ["root"]

The login information returned includes:

• Token duration: How log the token is valid for, typically expressed as the time-to-live (TTL) value in the format of a time string (i.e. "8h" or "30d"). The value is an infinity symbol for a root token because a root token does not have a TTL and can't be renewed, but is valid forever unless you revoke it.
• Accessor: A unique ID that can be used to lookup, renew, or revoke a token.
• Policies: One or more policies attached to the token that defines the actions authorized to be performed in Vault.

The default Vault TTL is 32 days. You can override the default TTL globally for your Vault cluster, or you can set a specific TTL on a role definition for a specific auth method. You can also set a max TTL which defines how long a token can be renewed for.

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.

The root token, shown in the code block above, is the only type of Vault token that can be set to never expire.

Token accessors are a unique ID that can be used to perform operations on a token such as renewing a token, looking up additional token metadata, or revoking a token.

Example:

$ vault token lookup -accessor AXvtYZloPbMotQ1TIzSgENdi
Key                 Value
---                 -----
accessor            AXvtYZloPbMotQ1TIzSgENdi
creation_time       1718635124
creation_ttl        1m
display_name        token
entity_id           n/a
expire_time         2024-06-17T10:39:44.264319-04:00
explicit_max_ttl    2m
id                  n/a
issue_time          2024-06-17T10:38:44.264326-04:00
meta                <nil>
num_uses            0
orphan              false
path                auth/token/create
period              1m
policies            [default]
renewable           true
ttl                 42s
type                service

A token accessor, unlike a token, does not provide access to Vault.

Example:

$ vault login AXvtYZloPbMotQ1TIzSgENdi
Error authenticating: error looking up token: Error making API request.

URL: GET http://127.0.0.1:8200/v1/auth/token/lookup-self
Code: 403. Errors:

* permission denied

All tokens include one or more policies. In the example above, the root token is attached. Another common policy to see attached to a token is the default policy. You will create policies in later tutorials to provide access to Vault.

What can you use a token accessor for?

Types of tokens

There are two main types of Vault tokens: service tokens and batch tokens. Vault persists the service tokens in its storage backend. You can renew a service token or revoke it as necessary.

Vault does not persist batch tokens. Batch tokens are encrypted binary large objects (blobs) that carry enough information to perform Vault actions. This makes batch tokens lightweight and scalable but they lack the flexibility and features of service tokens.

Token prefix

Tokens have a prefix that indicates their type.

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 affect 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 the lack of features with batch tokens, it's preferable to use service tokens in most use cases. There are, however, use cases for batch tokens. Consider 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 tokens can reduce the stress on the storage backend and improve the overall performance.

Batch tokens are designed to be lightweight with limited flexibility. The following table highlights the differences between batch tokens and service tokens.

Using a root token or a token with sudo capabilities can 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.

Example:

$ vault token create -policy="default" -period=24h
Key                  Value
---                  -----
token                hvs.CAESIIG_PILmULFYOsEyWHxkZ2mF2a8V...example...p3ZnpWbDF1RUNjUkNTZEg
token_accessor       kfhjoayUCHo1yjdbT0YWvlJ1
token_duration       24h
token_renewable      true
token_policies       ["default"]
identity_policies    []
policies             ["default"]

Another type of service token is an orphan token. Like periodic tokens, you must create an orphan token with a root token or a token with sudo capability.

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.

Example:

$ vault token create -orphan -policy=default
Key                  Value
---                  -----
token                hvs.CAESICg2bhAsyvurkbzEV8JgLaCF-...example...2pqanZCVWJHMGNZZXA
token_accessor       9UMZHtvJf1XKPfPrRlIgV062
token_duration       768h
token_renewable      true
token_policies       ["default"]
identity_policies    []
policies             ["default"]

Renew a token in Vault

A token can be renewed multiple times up to the maximum TTL set for the token.

Example:

$ vault token create -policy="default" -period=1m -explicit-max-ttl=2m
Key                  Value
---                  -----
token                hvs.CAESINxleXnwDWoVm...example...MDU4bGFGcUNjMVZnTzhZMDA
token_accessor       oesNHFzPatMS2t9gxDQIK6Iq
token_duration       1m
token_renewable      true
token_policies       ["default"]
identity_policies    []
policies             ["default"]

The token will be valid for a period of 1m and can be renewed for up to 2m based on the explicit-max-ttl value.

The token, even if renewed, will not be valid beyond the explicit-max-ttl value.

Example:

$ vault token renew -accessor Ebohe1EpUuHGLiCaNYq56Z60
WARNING! The following warnings were returned from Vault:

  * TTL of "1m" exceeded the effective max_ttl of "38s"; TTL value is capped
  accordingly

Key                  Value
---                  -----
token                n/a
token_accessor       Ebohe1EpUuHGLiCaNYq56Z60
token_duration       38s
token_renewable      true
token_policies       ["default"]
identity_policies    []
policies             ["default"]

Revoke a token in Vault

A token will no longer be valid once the TTL or max TTL is reached. You can also manually revoke a token. Consider a scenario where a token was commited to source. This would create a security incident because a valid token can be seen in the source code repository. In this type of scenario, you can revoke a token manually.

Example:

$ vault token create -policy="default" -period=10m
Key                  Value
---                  -----
token                hvs.CAESIJAuOGTpVr...example...VAxU25Ib3pKdEtMcEJrQWc
token_accessor       6SWPsqmEA5CubIiYW6DSxwRg
token_duration       10m
token_renewable      true
token_policies       ["default"]
identity_policies    []
policies             ["default"]

You can manually revoke the token using either the token, or the token_accessor.

$ vault token revoke hvs.CAESIJAuOGTpVr...example...VAxU25Ib3pKdEtMcEJrQWc
Success! Revoked token (if it existed)

Summary

Tokens are central to understanding and managing Vault. Vault issues a token upon successful authentication. Tokens include metadata for managing the token, as well as policies that defines the actions a token is able to do in Vault. Vault supports different types of tokens depending on the type of workload authenticating with Vault.