Hashicorp Vault

How to rotate a Vault root token

Jeremy Chauvet

Feb 25, 2024 — 3 min read

In this quick tutorial, you will learn how to rotate an Hashicorp Vault root token within 2 minutes.

Step 1 - Login to Vault

As this operation request specific rights, let's connect to Vault using the CLI:

➜  ~ 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.mY48tW5VVMB8UpxO4tPXuF50
token_accessor       iX11es7bYXAb3Zhgn5TibLkf
token_duration       ∞
token_renewable      false
token_policies       ["root"]
identity_policies    []
policies             ["root"]

On this example, I'm using the root token.

Step 2 - Create a new root token

Let's init the process using the generator-root command:

➜  ~ vault operator generate-root -init
A One-Time-Password has been generated for you and is shown in the OTP field.
You will need this value to decode the resulting root token, so keep it safe.
Nonce         f24771c2-0736-4c54-1176-0af57e250f36
Started       true
Progress      0/3
Complete      false
OTP           j3jygDEGhcvcJxvn3u4bceri5T9m
OTP Length    28

Note the OTP value, you will need it later to decode the generated root token. Now, remove the init parameter and launch the command again (unseal keys will be needed):

➜  ~ vault operator generate-root
Operation nonce: f24771c2-0736-4c54-1176-0af57e250f36
Unseal Key (will be hidden):
Nonce       f24771c2-0736-4c54-1176-0af57e250f36
Started     true
Progress    1/3
Complete    false
➜  ~ vault operator generate-root
Operation nonce: f24771c2-0736-4c54-1176-0af57e250f36
Unseal Key (will be hidden):
Nonce       f24771c2-0736-4c54-1176-0af57e250f36
Started     true
Progress    2/3
Complete    false
➜  ~ vault operator generate-root
Operation nonce: f24771c2-0736-4c54-1176-0af57e250f36
Unseal Key (will be hidden):
Nonce            f24771c2-0736-4c54-1176-0af57e250f36
Started          true
Progress         3/3
Complete         true
Encoded Token    AkUZVy0NPAIPORkyczEVHgVGdwQ6XCRYACVUKg

As 3 unseal keys are needed to unseal my cluster, I had to relaunch the command 3 times, as shown by the "Progress" row.

Once the process is finished, Vault will provide you with a new, encoded token. Let decode it using the OTP:

➜  ~ vault operator generate-root -decode=AkUZVy0NPAIPORkyczEVHgVGdwQ6XCRYACVUKg -otp=j3jygDEGhcvcJxvn3u4bceri5T9m
hvs.JIyEgZoQ9Icp63CfY9V15qmG

You have successfully generated a new root token, which means to have now two root tokens:

The old one: hvs.mY48tW5VVMB8UpxO4tPXuF50
The newly generated: hvs.JIyEgZoQ9Icp63CfY9V15qmG

Step 3 - Revoke the old root token

➜  ~ vault token revoke hvs.mY48tW5VVMB8UpxO4tPXuF50
Success! Revoked token (if it existed)

You're done, you have successfully rotate the root token. Keep in mind using or persisting this token is highly discouraged by Hashicorp:

[...] the Vault team recommends that root tokens are only used for just enough initial setup (usually, setting up auth methods and policies necessary to allow administrators to acquire more limited tokens) or in emergencies, and are revoked immediately after they are no longer needed.