Intekhab Rizvi

Chapter 24 / 28

Revoking and Regenerating the Root Token

HashiCorp Vault For Beginners6 min read

In a production Vault deployment, the root token is the most powerful credential in the system. It is designed to bypass all policies, granting full administrative access. While this makes it essential during setup and bootstrapping, retaining the root token after initial configuration introduces significant risk.

In this chapter, we’ll cover:

  1. Why revoking the root token is strongly recommended
  2. How to revoke the root token securely
  3. How to regenerate the root token using quorum
  4. Enabling a stable operational authentication method (e.g., userpass) beforehand
  5. Understanding mlock, the Vault data directory, and best practices
  6. A complete walkthrough with all commands included

Why Revoke the Root Token?

The root token:

  • Has unrestricted access to Vault.
  • Bypasses policies and controls.
  • If leaked or misused, compromises the entire Vault cluster.

Root Token in Production = Liability

Best practice:

  • Use it to bootstrap Vault.
  • Create real users and assign policies.
  • Then revoke it.

Regeneration of the root token should be a deliberate, audited, multi-party operation, not a casual fallback.

Pre-Requisite: Enable the userpass Auth Method

Before revoking the root token, ensure you have an alternate administrative login.

Here, we'll use the built-in userpass auth method.

Step 1: Enable userpass Auth

vault auth enable userpass

Step 2: Create an Admin Policy

Create a file admin-policy.hcl with below content:

path "*" {
  capabilities = ["create", "read", "update", "delete", "list", "sudo"]
}

Create the policy using the admin-policy.hcl:

vault policy write admin admin-policy.hcl

Make sure you are inside the same folder where you have saved the admin-policy.hcl

Step 3: Create a Vault Admin User

vault write auth/userpass/users/vaultadmin \
  password="123456" \
  policies="admin"

Login and verify:

vault login -method=userpass username=vaultadmin password=123456

The output of last there commands will be like below.

Screenshot for “Step 3: Create a Vault Admin User” in chapter 24: Revoking and Regenerating the Root Token

Now you're ready to retire the root token.

Revoking the Root Token

If you're logged in as root and want to revoke your own token:

vault token revoke -self

Or to revoke a specific root token:

vault token revoke <root_token>

Before revoking, always confirm another fully privileged user or group has operational access to Vault.

Regenerating the Root Token (When Needed)

Vault supports a secure, quorum-based process to regenerate the root token. This process ensures that no single person can generate the root token alone.

Step 1: Begin Root Token Regeneration Process

Start the root token generation process:

vault operator generate-root -init

You will receive two important values:

  • One-Time OTP (OTP): A short-lived password used to encrypt the new root token.
  • Nonce: A unique identifier for this regeneration attempt. It must be passed with every unseal key submission.

*What is OTP and Nonce?* The OTP is used to encrypt the root token. You’ll need it at the end to decrypt the result. The Nonce uniquely identifies this regeneration attempt. Without it, Vault won't accept unseal key submissions.

Example output:

Screenshot for “Step 1: Begin Root Token Regeneration Process” in chapter 24: Revoking and Regenerating the Root Token

Step 2: Provide Unseal Key Shares (With Nonce)

Each key holder submits their unseal key, along with the nonce:

vault operator generate-root -nonce=<nonce> <unseal_key>

Repeat this step with each unique key until the configured key threshold is met (e.g., 3 of 5 unseal keys).

Once quorum is reached, Vault outputs the Encoded Root Token.

Screenshot for “Step 2: Provide Unseal Key Shares (With Nonce)” in chapter 24: Revoking and Regenerating the Root Token

Step 3: Decrypt the Root Token (Using OTP)

Vault returns the token like this:

Encoded Token: xxxxxxxxxx

Now decrypt the encoded token using the OTP you received earlier:

vault operator generate-root -decode <encoded_token> -otp <One-time-otp>

You’ll then receive the actual root token.

Screenshot for “Step 3: Decrypt the Root Token (Using OTP)” in chapter 24: Revoking and Regenerating the Root Token

Recap

  • The root token should not be kept around in production systems.
  • Always create admin users and test their login before revoking the root token.
  • The root token can be regenerated using quorum-based approval from unseal key holders.
  • Vault’s data directory and mlock settings are critical for performance and security.