open-vault/website/source/docs/concepts/tokens.html.md

285 lines
13 KiB
Markdown
Raw Normal View History

2015-04-18 00:18:20 +00:00
---
layout: "docs"
page_title: "Tokens"
New Docs Website (#5535) * conversion stage 1 * correct image paths * add sidebar title to frontmatter * docs/concepts and docs/internals * configuration docs and multi-level nav corrections * commands docs, index file corrections, small item nav correction * secrets converted * auth * add enterprise and agent docs * add extra dividers * secret section, wip * correct sidebar nav title in front matter for apu section, start working on api items * auth and backend, a couple directory structure fixes * remove old docs * intro side nav converted * reset sidebar styles, add hashi-global-styles * basic styling for nav sidebar * folder collapse functionality * patch up border length on last list item * wip restructure for content component * taking middleman hacking to the extreme, but its working * small css fix * add new mega nav * fix a small mistake from the rebase * fix a content resolution issue with middleman * title a couple missing docs pages * update deps, remove temporary markup * community page * footer to layout, community page css adjustments * wip downloads page * deps updated, downloads page ready * fix community page * homepage progress * add components, adjust spacing * docs and api landing pages * a bunch of fixes, add docs and api landing pages * update deps, add deploy scripts * add readme note * update deploy command * overview page, index title * Update doc fields Note this still requires the link fields to be populated -- this is solely related to copy on the description fields * Update api_basic_categories.yml Updated API category descriptions. Like the document descriptions you'll still need to update the link headers to the proper target pages. * Add bottom hero, adjust CSS, responsive friendly * Add mega nav title * homepage adjustments, asset boosts * small fixes * docs page styling fixes * meganav title * some category link corrections * Update API categories page updated to reflect the second level headings for api categories * Update docs_detailed_categories.yml Updated to represent the existing docs structure * Update docs_detailed_categories.yml * docs page data fix, extra operator page remove * api data fix * fix makefile * update deps, add product subnav to docs and api landing pages * Rearrange non-hands-on guides to _docs_ Since there is no place for these on learn.hashicorp, we'll put them under _docs_. * WIP Redirects for guides to docs * content and component updates * font weight hotfix, redirects * fix guides and intro sidenavs * fix some redirects * small style tweaks * Redirects to learn and internally to docs * Remove redirect to `/vault` * Remove `.html` from destination on redirects * fix incorrect index redirect * final touchups * address feedback from michell for makefile and product downloads
2018-10-19 15:40:11 +00:00
sidebar_title: "Tokens"
2015-04-18 00:18:20 +00:00
sidebar_current: "docs-concepts-tokens"
description: |-
Tokens are a core auth method in Vault. Concepts and important features.
2015-04-18 00:18:20 +00:00
---
# Tokens
Tokens are the core method for _authentication_ within Vault. Tokens
can be used directly or [auth methods](/docs/concepts/auth.html)
2015-04-18 00:18:20 +00:00
can be used to dynamically generate tokens based on external identities.
If you've gone through the getting started guide, you probably noticed that
`vault server -dev` (or `vault operator init` for a non-dev server) outputs an
2015-04-18 00:18:20 +00:00
initial "root token." This is the first method of authentication for Vault.
It is also the only auth method that cannot be disabled.
2015-04-18 00:18:20 +00:00
As stated in the [authentication concepts](/docs/concepts/auth.html),
2016-08-13 21:05:31 +00:00
all external authentication mechanisms, such as GitHub, map down to dynamically
created tokens. These tokens have all the same properties as a normal manually
created token.
2015-04-18 00:18:20 +00:00
2016-08-13 21:05:31 +00:00
Within Vault, tokens map to information. The most important information mapped
to a token is a set of one or more attached
[policies](/docs/concepts/policies.html). These policies control what the token
holder is allowed to do within Vault. Other mapped information includes
metadata that can be viewed and is added to the audit log, creation time, last
renewal time, and more.
2015-04-18 00:18:20 +00:00
~> Note that external to Vault, tokens are to be considered opaque values
by users and as such, their structure is both currently undocumented and
subject to change.
2016-08-13 21:05:31 +00:00
Read on for a deeper dive into token concepts.
2015-04-18 00:18:20 +00:00
2018-10-15 16:56:24 +00:00
## Token Types
2015-04-18 00:18:20 +00:00
2018-10-15 16:56:24 +00:00
As of Vault 1.0, there are two types of tokens: `service` tokens and `batch`
tokens. A section near the bottom of this page contains detailed information
about their differences, but it is useful to understand other token concepts
first. The features in the following sections all apply to service tokens, and
their applicability to batch tokens is discussed later.
## The Token Store
2015-04-18 00:18:20 +00:00
2016-08-13 21:05:31 +00:00
Often in documentation or in help channels, the "token store" is referenced.
This is the same as the [`token` authentication
2017-03-16 19:04:36 +00:00
backend](/docs/auth/token.html). This is a special
2016-08-13 21:05:31 +00:00
backend in that it is responsible for creating and storing tokens, and cannot
be disabled. It is also the only auth method that has no login
2016-08-13 21:05:31 +00:00
capability -- all actions require existing authenticated tokens.
2015-04-18 00:18:20 +00:00
2018-10-15 16:56:24 +00:00
## Root Tokens
2015-04-18 00:18:20 +00:00
2016-08-13 21:05:31 +00:00
Root tokens are tokens that have the `root` policy attached to them. Root
tokens can do anything in Vault. _Anything_. In addition, they are the only
type of token within Vault that can be set to never expire without any renewal
2018-10-15 16:56:24 +00:00
needed. As a result, it is purposefully hard to create root tokens; in fact
there are only three ways to create root tokens:
2015-04-18 00:18:20 +00:00
1. The initial root token generated at `vault operator init` time -- this token has no
2016-08-13 21:05:31 +00:00
expiration
2. By using another root token; a root token with an expiration cannot create a
root token that never expires
3. By using `vault operator generate-root` ([example](/guides/operations/generate-root.html))
with the permission of a quorum of unseal key holders
2015-04-18 00:18:20 +00:00
2016-08-13 21:05:31 +00:00
Root tokens are useful in development but should be extremely carefully guarded
in production. In fact, the Vault team recommends that root tokens are only
used for just enough initial setup (usually, setting up auth methods
2016-08-13 21:05:31 +00:00
and policies necessary to allow administrators to acquire more limited tokens)
or in emergencies, and are revoked immediately after they are no longer needed.
If a new root token is needed, the `operator generate-root` command and associated
[API endpoint](/api/system/generate-root.html) can be used to generate one on-the-fly.
2016-08-13 21:05:31 +00:00
It is also good security practice for there to be multiple eyes on a terminal
whenever a root token is live. This way multiple people can verify as to the
tasks performed with the root token, and that the token was revoked immediately
after these tasks were completed.
2018-10-15 16:56:24 +00:00
## Token Hierarchies and Orphan Tokens
2016-08-13 21:05:31 +00:00
Normally, when a token holder creates new tokens, these tokens will be created
as children of the original token; tokens they create will be children of them;
and so on. When a parent token is revoked, all of its child tokens -- and all
of their leases -- are revoked as well. This ensures that a user cannot escape
revocation by simply generating a never-ending tree of child tokens.
Often this behavior is not desired, so users with appropriate access can create
`orphan` tokens. These tokens have no parent -- they are the root of their own
token tree. These orphan tokens can be created:
1. Via the `auth/token/create-orphan` endpoint
2. By having `sudo` capability or `root` policy when accessing
`auth/token/create` and setting the `orphan` parameter to `true`
3. Via token store roles
4. By logging in with any other (non-`token`) auth method
2016-08-13 21:05:31 +00:00
Users with appropriate permissions can also use the `auth/token/revoke-orphan`
endpoint, which revokes the given token but rather than revoke the rest of the
tree, it instead sets the tokens' immediate children to be orphans. Use with
caution!
2018-10-15 16:56:24 +00:00
## Token Accessors
When tokens are created, a token accessor is also created and returned. This
accessor is a value that acts as a reference to a token and can only be used to
perform limited actions:
1. Look up a token's properties (not including the actual token ID)
2. Look up a token's capabilities on a path
3. Revoke the token
There are many useful workflows around token accessors. As an example, a
service that creates tokens on behalf of another service (such as the
[Nomad](https://www.nomadproject.io/) scheduler) can store the accessor
correlated with a particular job ID. When the job is complete, the accessor can
be used to instantly revoke the token given to the job and all of its leased
credentials, limiting the chance that a bad actor will discover and use them.
2017-09-21 21:14:40 +00:00
Audit devices can optionally be set to not obfuscate token accessors in audit
logs. This provides a way to quickly revoke tokens in case of an emergency.
2017-09-21 21:14:40 +00:00
However, it also means that the audit logs can be used to perform a larger-scale
denial of service attack.
Finally, the only way to "list tokens" is via the `auth/token/accessors`
command, which actually gives a list of token accessors. While this is still a
dangerous endpoint (since listing all of the accessors means that they can then
be used to revoke all tokens), it also provides a way to audit and revoke the
currently-active set of tokens.
2018-10-15 16:56:24 +00:00
## Token Time-To-Live, Periodic Tokens, and Explicit Max TTLs
2016-08-13 21:05:31 +00:00
Every non-root token has a time-to-live (TTL) associated with it, which is a
current period of validity since either the token's creation time or last
renewal time, whichever is more recent. (Root tokens may have a TTL associated,
but the TTL may also be 0, indicating a token that never expires). After the
current TTL is up, the token will no longer function -- it, and its associated
leases, are revoked.
If the token is renewable, Vault can be asked to extend the token validity
period using `vault token renew` or the appropriate renewal endpoint. At this
2016-08-13 21:05:31 +00:00
time, various factors come into play. What happens depends upon whether the
token is a periodic token (available for creation by `root`/`sudo` users, token
store roles, or some auth methods), has an explicit maximum TTL
2016-08-13 21:05:31 +00:00
attached, or neither.
2018-10-15 16:56:24 +00:00
### The General Case
2016-08-13 21:05:31 +00:00
In the general case, where there is neither a period nor explicit maximum TTL
value set on the token, the token's lifetime since it was created will be
compared to the maximum TTL. This maximum TTL value is dynamically generated
and can change from renewal to renewal, so the value cannot be displayed when a
token's information is looked up. It is based on a combination of factors:
1. The system max TTL, which is 32 days but can be changed in Vault's
configuration file.
2016-08-13 21:05:31 +00:00
2. The max TTL set on a mount using [mount
2017-03-17 18:27:20 +00:00
tuning](/api/system/mounts.html). This value
2016-08-13 21:05:31 +00:00
is allowed to override the system max TTL -- it can be longer or shorter,
and if set this value will be respected.
3. A value suggested by the auth method that issued the token. This
2016-08-13 21:05:31 +00:00
might be configured on a per-role, per-group, or per-user basis. This value
is allowed to be less than the mount max TTL (or, if not set, the system max
TTL), but it is not allowed to be longer.
Note that the values in (2) and (3) may change at any given time, which is why
a final determination about the current allowed max TTL is made at renewal time
using the current values. It is also why it is important to always ensure that
the TTL returned from a renewal operation is within an allowed range; if this
value is not extending, likely the TTL of the token cannot be extended past its
current value and the client may want to reauthenticate and acquire a new
token. However, outside of direct operator interaction, Vault will never revoke
a token before the returned TTL has expired.
2018-10-15 16:56:24 +00:00
### Explicit Max TTLs
2016-08-13 21:05:31 +00:00
Tokens can have an explicit max TTL set on them. This value becomes a hard
limit on the token's lifetime -- no matter what the values in (1), (2), and (3)
from the general case are, the token cannot live past this explicitly-set
value. This has an effect even when using periodic tokens to escape the normal
TTL mechanism.
2018-10-15 16:56:24 +00:00
### Periodic Tokens
2016-08-13 21:05:31 +00:00
In some cases, having a token be revoked would be problematic -- for instance,
if a long-running service needs to maintain its SQL connection pool over a long
period of time. In this scenario, a periodic token can be used. Periodic tokens
can be created in a few ways:
1. By having `sudo` capability or a `root` token with the `auth/token/create`
endpoint
2. By using token store roles
3. By using an auth method that supports issuing these, such as
2016-08-13 21:05:31 +00:00
AppRole
At issue time, the TTL of a periodic token will be equal to the configured
period. At every renewal time, the TTL will be reset back to this configured
period, and as long as the token is successfully renewed within each of these
periods of time, it will never expire. Outside of `root` tokens, it is
currently the only way for a token in Vault to have an unlimited lifetime.
The idea behind periodic tokens is that it is easy for systems and services to
perform an action relatively frequently -- for instance, every two hours, or
even every five minutes. Therefore, as long as a system is actively renewing
this token -- in other words, as long as the system is alive -- the system is
allowed to keep using the token and any associated leases. However, if the
system stops renewing within this period (for instance, if it was shut down),
the token will expire relatively quickly. It is good practice to keep this
period as short as possible, and generally speaking it is not useful for humans
to be given periodic tokens.
There are a few important things to know when using periodic tokens:
* When a periodic token is created via a token store role, the _current_ value
of the role's period setting will be used at renewal time
* A token with both a period and an explicit max TTL will act like a periodic
token but will be revoked when the explicit max TTL is reached
2018-10-15 16:56:24 +00:00
## CIDR-Bound Tokens
Some tokens are able to be bound to CIDR(s) that restrict the range of client
IPs allowed to use them. These affect all tokens except for non-expiring root
tokens (those with a TTL of zero). If a root token has an expiration, it also
is affected by CIDR-binding.
2018-10-15 16:56:24 +00:00
## Token Types in Detail
There are currently two types of tokens.
### Service Tokens
Service tokens are what users will generally think of as "normal" Vault tokens.
They support all features, such as renewal, revocation, creating child tokens,
and more. The are correspondingly heavyweight to create and track.
### Batch Tokens
Batch tokens are encrypted blobs that carry enough information for them to
2018-10-15 16:56:24 +00:00
be used for Vault actions, but they require no storage on disk to track them.
As a result they are extremely lightweight and scalable, but lack most of the
flexibility and features of service tokens.
### Token Type Comparison
This reference chart describes the difference in behavior between service and
batch tokens.
| | Service Tokens | Batch Tokens |
|---|---:|---:|
| Can Be Root Tokens | Yes | No |
| Can Create Child Tokens | Yes | No |
| Can be Renewable | Yes | No |
| Can be Periodic | Yes | No |
| Can have Explicit Max TTL | Yes | No (always uses a fixed TTL) |
| Has Accessors | Yes | No |
| Has Cubbyhole | Yes | No |
| Revoked with Parent (if not orphan) | Yes | Stops Working |
| Dynamic Secrets Lease Assignment | Self | Parent (if not orphan) |
| Can be Used Across Performance Replication Clusters | No | Yes (if orphan) |
| Creation Scales with Performance Standby Node Count | No | Yes |
| Cost | Heavyweight; multiple storage writes per token creation | Lightweight; no storage cost for token creation |
### Service vs. Batch Token Lease Handling
#### Service Tokens
Leases created by service tokens (including child tokens' leases) are tracked
along with the service token and revoked when the token expires.
#### Batch Tokens
Leases created by batch tokens are constrained to the remaining TTL of the
batch tokens and, if the batch token is not an orphan, are tracked by the
parent. They are revoked when the batch token's TTL expires, or when the batch
token's parent is revoked (at which point the batch token is also denied access
to Vault).
As a corollary, batch tokens can be used across performance replication
clusters, but only if they are orphan, since non-orphan tokens will not be able
to ensure the validity of the parent token.