Oct 19-21 HashiConf Global is live. Join Now
Type '/' to Search

Generate Root Tokens Using Unseal Keys

This tutorial also appears in: Interactive.

It is generally considered a best practice not to persist root tokens. Use the root token only for just enough initial setup. Once you enabled an auth method with appropriate policies allowing Vault admins to log in and perform operational tasks, the admins should authenticate with Vault instead of using the root token.

In case of an emergency when a root token is absolutely necessary, Vault operator should generate a new root token using the operator generate-root command. This tutorial demonstrates the steps to regenerate a root token.

First, make sure to unseal the vault using the existing quorum of unseal keys. You do not need to be authenticated to generate a new root token, but the Vault must be unsealed and a quorum of unseal keys must be available.

$ vault operator unseal
Unseal Key (will be hidden):

$ vault operator unsealUnseal Key (will be hidden):

»Use one-time password (OTP)

  1. Initialize a root token generation.

    $ 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         15565c79-cc9e-5e64-b986-8506e7bd1918
Started       true
Progress      0/1
Complete      false
OTP           5JFQaH76Ky2TIuSt4SPvO1CGkx
OTP Length    26

    $ 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         15565c79-cc9e-5e64-b986-8506e7bd1918Started       trueProgress      0/1Complete      falseOTP           5JFQaH76Ky2TIuSt4SPvO1CGkxOTP Length    26

    Nonce and one-time password (OTP) are generated. The nonce value should be distributed to all unseal key (recovery key if auto-unseal is used) holders.

    NOTE: You will need the OTP value later to decode the generated root token.

  2. Each unseal key holder provides their unseal key.

    $ vault operator generate-root

Root generation operation nonce: f67f4da3-4ae4-68fb-4716-91da6b609c3e
Unseal Key (will be hidden):

    $ vault operator generate-root
Root generation operation nonce: f67f4da3-4ae4-68fb-4716-91da6b609c3eUnseal Key (will be hidden):

    If there is a tty, Vault will prompt for the key and automatically complete the nonce value. If there is no tty, or if the value is piped from stdin, the user must specify the nonce value from the -init operation.

    $ echo $UNSEAL_KEY | vault operator generate-root -nonce=f67f4da3... -

    $ echo $UNSEAL_KEY | vault operator generate-root -nonce=f67f4da3... -

  3. When the quorum of unseal keys (or recovery keys) are supplied, the final user will also get the encoded root token.

    $ vault operator generate-root

Root generation operation nonce: f67f4da3-4ae4-68fb-4716-91da6b609c3e
Unseal Key (will be hidden):

Nonce            f67f4da3-4ae4-68fb-4716-91da6b609c3e
Started          true
Progress         5/5
Complete         true
Encoded Token    IxJpyqxn3YafOGhqhvP6cQ==

    $ vault operator generate-root
Root generation operation nonce: f67f4da3-4ae4-68fb-4716-91da6b609c3eUnseal Key (will be hidden):
Nonce            f67f4da3-4ae4-68fb-4716-91da6b609c3eStarted          trueProgress         5/5Complete         trueEncoded Token    IxJpyqxn3YafOGhqhvP6cQ==

  4. Decode the encoded token using the OTP generated during the initialization.

    $ vault operator generate-root \
  -decode=IxJpyqxn3YafOGhqhvP6cQ== \
  -otp=mOXx7iVimjE6LXQ2Zna6NA==

24bde68f-3df3-e137-cf4d-014fe9ebc43f

    $ vault operator generate-root \  -decode=IxJpyqxn3YafOGhqhvP6cQ== \  -otp=mOXx7iVimjE6LXQ2Zna6NA==
24bde68f-3df3-e137-cf4d-014fe9ebc43f

NOTE: An interactive tutorial is also available if you do not have a Vault environment to perform the steps described in this tutorial. Click the Show Terminal button to start.

»Use PGP

  1. Initialize a root token generation, providing the path to a GPG public key or keybase username of a user to encrypted the resulting token.

    $ vault operator generate-root -init -pgp-key=keybase:sethvargo

Nonce              e24dec5e-f1ea-2dfe-ecce-604022006976
Started            true
Progress           0/5
Complete           false
PGP Fingerprint    e2f8e2974623ba2a0e933a59c921994f9c27e0ff

    $ vault operator generate-root -init -pgp-key=keybase:sethvargo
Nonce              e24dec5e-f1ea-2dfe-ecce-604022006976Started            trueProgress           0/5Complete           falsePGP Fingerprint    e2f8e2974623ba2a0e933a59c921994f9c27e0ff

    The nonce value should be distributed to all unseal key holders.

  2. Each unseal key holder providers their unseal key.

    $ vault operator generate-root

Root generation operation nonce: e24dec5e-f1ea-2dfe-ecce-604022006976
Unseal Key (will be hidden): ...

    $ vault operator generate-root
Root generation operation nonce: e24dec5e-f1ea-2dfe-ecce-604022006976Unseal Key (will be hidden): ...

    If there is a tty, Vault will prompt for the key and automatically complete the nonce value. If there is no tty, or if the value is piped from stdin, the user must specify the nonce value from the -init operation.

    $ echo $UNSEAL_KEY | vault operator generate-root -nonce=f67f4da3... -

    $ echo $UNSEAL_KEY | vault operator generate-root -nonce=f67f4da3... -

  3. When the quorum of unseal keys are supplied, the final user will also get the encoded root token.

    $ vault operator generate-root

Root generation operation nonce: e24dec5e-f1ea-2dfe-ecce-604022006976
Unseal Key (will be hidden):

Nonce                 e24dec5e-f1ea-2dfe-ecce-604022006976
Started               true
Progress              1/1
Complete              true
PGP Fingerprint       e2f8e2974623ba2a0e933a59c921994f9c27e0ff
Encoded Token         wcFMA0RVkFtoqzRlARAAI3Ux8kdSpfgXdF9mg...

    $ vault operator generate-root
Root generation operation nonce: e24dec5e-f1ea-2dfe-ecce-604022006976Unseal Key (will be hidden):
Nonce                 e24dec5e-f1ea-2dfe-ecce-604022006976Started               trueProgress              1/1Complete              truePGP Fingerprint       e2f8e2974623ba2a0e933a59c921994f9c27e0ffEncoded Token         wcFMA0RVkFtoqzRlARAAI3Ux8kdSpfgXdF9mg...

  4. Decrypt the encrypted token using associated private key.

    $ echo "wcFMA0RVkFtoqzRlARAAI3Ux8kdSpfgXdF9mg..." | base64 --decode | gpg --decrypt

d0f71e9b-ebff-6d8a-50ae-b8859f2e5671

    $ echo "wcFMA0RVkFtoqzRlARAAI3Ux8kdSpfgXdF9mg..." | base64 --decode | gpg --decrypt
d0f71e9b-ebff-6d8a-50ae-b8859f2e5671

    or via keybase:

    $ echo "wcFMA0RVkFtoqzRlARAAI3Ux8kdSpfgXdF9mg..." | base64 --decode | keybase pgp decrypt

d0f71e9b-ebff-6d8a-50ae-b8859f2e5671

    $ echo "wcFMA0RVkFtoqzRlARAAI3Ux8kdSpfgXdF9mg..." | base64 --decode | keybase pgp decrypt
d0f71e9b-ebff-6d8a-50ae-b8859f2e5671
stdin: is not a tty