»Generate Root Tokens Using Unseal Keys
It is generally considered a best practice to not persist
root tokens. Instead a root token should be generated using
Vault's operator generate-root
command only when absolutely necessary. This
guide demonstrates regenerating a root token.
-
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.
»Using OTP
In this method, an OTP is XORed with the generated token on final output.
-
Generate a one-time password (OTP) to use for XORing the resulting token:
$ vault operator generate-root -generate-otp
mOXx7iVimjE6LXQ2Zna6NA==
$ vault operator generate-root -generate-otpmOXx7iVimjE6LXQ2Zna6NA==
Save this OTP because you will need it to get the decoded final root token.
-
Initialize a root token generation, providing the OTP code from the step
above:
$ vault operator generate-root -init -otp=mOXx7iVimjE6LXQ2Zna6NA==
Nonce f67f4da3-4ae4-68fb-4716-91da6b609c3e
Started true
Progress 0/5
Complete false
$ vault operator generate-root -init -otp=mOXx7iVimjE6LXQ2Zna6NA==Nonce f67f4da3-4ae4-68fb-4716-91da6b609c3eStarted trueProgress 0/5Complete false
The nonce value should be distributed to all unseal key holders.
-
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-rootRoot 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... -
-
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: f67f4da3-4ae4-68fb-4716-91da6b609c3e
Unseal Key (will be hidden):
Nonce f67f4da3-4ae4-68fb-4716-91da6b609c3e
Started true
Progress 5/5
Complete true
Root Token IxJpyqxn3YafOGhqhvP6cQ==
$ vault operator generate-rootRoot generation operation nonce: f67f4da3-4ae4-68fb-4716-91da6b609c3eUnseal Key (will be hidden):
Nonce f67f4da3-4ae4-68fb-4716-91da6b609c3eStarted trueProgress 5/5Complete trueRoot Token IxJpyqxn3YafOGhqhvP6cQ==
-
Decode the encoded token using the OTP:
$ 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
»Using PGP
-
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:sethvargoNonce e24dec5e-f1ea-2dfe-ecce-604022006976Started trueProgress 0/5Complete falsePGP Fingerprint e2f8e2974623ba2a0e933a59c921994f9c27e0ff
The nonce value should be distributed to all unseal key holders.
-
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-rootRoot 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... -
-
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
Root Token wcFMA0RVkFtoqzRlARAAI3Ux8kdSpfgXdF9mg...
$ vault operator generate-rootRoot generation operation nonce: e24dec5e-f1ea-2dfe-ecce-604022006976Unseal Key (will be hidden):
Nonce e24dec5e-f1ea-2dfe-ecce-604022006976Started trueProgress 1/1Complete truePGP Fingerprint e2f8e2974623ba2a0e933a59c921994f9c27e0ffRoot Token wcFMA0RVkFtoqzRlARAAI3Ux8kdSpfgXdF9mg...
-
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