KodeKloud Notes

In Vault, a root token is the ultimate superuser credential. It carries the root policy, granting unrestricted access to every Vault operation. This guide covers what root tokens are, how to use them securely, and the various ways to generate or recover them.

The image is a slide about root tokens, explaining their unlimited access, lack of expiration, and best practices for usage and revocation. It includes colorful text highlights and a cartoon character in the corner.

What Is a Root Token?

A root token:

Carries the root policy, allowing any Vault operation
Is non-renewable by default (token_renewable=false)
Has no expiration (TTL is ∞)

Running a lookup against a root token shows:

$ vault token lookup s.<root-token>
Key                Value
---                -----
token              s.<root-token>
token_duration     ∞
token_renewable    false
policies           ["root"]

Note

You can use an existing root token to create a new token with a finite TTL if desired.

Best Practices for Root Tokens

Root tokens should be handled with extreme caution:

Scenario	Usage
Initial Setup	Perform your Vault initialization tasks.
Testing Integrations	Validate new auth methods (e.g., LDAP, OIDC).
Emergency Recovery	Regenerate in a crisis when standard auth is unavailable.

Warning

Root tokens grant unlimited access. Always revoke them immediately after use to avoid security risks:

$ vault token revoke s.<root-token>
Success! Revoked token (if it existed)

Generating Root Tokens

You can obtain a root token through three primary methods:

Method	When to Use	Command
Initialization	First-time Vault setup	`vault operator init`
Using an Existing Token	Create additional root-level tokens	`vault token create`
Using Unseal/Recovery Keys	Emergency recovery when Vault is sealed	`vault operator generate-root`

1. Initialization

During Vault initialization, the CLI outputs your initial root token:

$ vault operator init
# ...
Initial Root Token: s.<initial-root-token>
# ...

2. Creating from an Existing Root Token

If you already have a root token, log in and issue a new one:

$ vault login s.<existing-root-token>
Success! You are now authenticated.

$ vault token create
Key                Value
---                -----
token              s.<new-root-token>
token_duration     ∞
token_policies     ["root"]
policies           ["root"]

3. Emergency Recovery with Unseal/Recovery Keys

In critical scenarios where Vault’s normal auth is down, you can regenerate a root token using a quorum of recovery keys.

The image explains how to create a root token using unseal/recovery keys, detailing a three-step process involving initialization, key holder actions, and decoding.

Step 1: Initialize Root Generation

Generate a nonce and one-time password (OTP):

$ vault operator generate-root -init
Nonce        5b6e3831-2a45-4695-7757-5810074d36c8
Started      true
Progress     0/3
Complete     false
OTP          E87jF6ZeJo8NjJwytl7mvKLER
OTP Length   26

Step 2: Submit Unseal Keys

Each key holder submits their unseal key. Repeat until the threshold is met (e.g., 3/3):

$ vault operator generate-root
Root generation operation nonce: 5b6e3831-2a45-...
Unseal Key (will be hidden):
Progress   1/3
Complete   false

Step 3: Decode the Root Token

Once the threshold is reached, use the OTP to decrypt the encoded token:

$ vault operator generate-root \
    -otp="E87jF6ZeJo8NjJwytl7mvKLER" \
    -decode="G2NeKUZgXTsYYxILAC9ZFBguPw9ZBovFAs"
Root token: s.<recovered-root-token>

After resolving the emergency, revoke the recovered root token:

$ vault token revoke s.<recovered-root-token>
Success! Revoked token (if it existed)

Key Takeaways

Root tokens have unlimited privileges and no default expiration.
Restrict use to initial setup, testing, or emergency recovery only.
Always revoke root tokens immediately after use.
Generate root tokens via initialization, an existing root token, or a quorum of unseal keys.

References

Watch Video

Watch video content