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 long 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 Token (will be hidden): 

All tokens include one or more policies. In the example above, the root policy 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 committed 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.