Vault Server Basics

Table of contents
  1. Vault server
  2. Initialization
    1. GnuPG
    2. Vault init
  3. Unseal / Seal
    1. Unseal
    2. Seal
  4. Enabling authentication
    1. Enable userpass
  5. Policies
    1. Create a policy
    2. Add a policy

Vault server

When you first start the server with vault server, you need to first initialize and unseal it.

One option is to use the web UI, but you can also use the vault CLI.

You can access the web UI at http://localhost:8200/ui.

Initialization

In the beginning, Vault server is in a sealed state. There needs to be a master key to unseal it.

Upon initialization, Vault will attempt to split this key into pieces, and you will get to decide how many pieces it’ll be.

You will also have to decide the threshold of number of pieces that need to be put together in order to access the final key and unseal Vault.

One security hole of Vault was that the root initializer receives a raw text of all these keys.

Therefore, a recommended practice is that you encrypt these keys using a PGP key.

Have a PGP key for each piece of the key.

GnuPG

One way to do acquire a PGP key is with GnuPG.

# Follow prompts to create a PGP key
gpg --full-generate-key

# Export to disk as base64
gpg --export <key-id> | base64 > my-name.asc

Vault init

Now define a key share number and the threshold, and provide your PGP keys.

vault operator init \
  -key-shares=3 \ 
  -key-threshold=2 \
  -pgp-keys="person1.asc,person2.asc,person3.asc"
  -root-token-pgp-key="some.asc"

Then you will get, in this example, three PGP encrypted keys and a root token in your console.

Remember these encrypted keys and token.

The order in which you put pgp-keys matter. The first PGP key will be used to decrypt the first unseal key, the second will be used to decrypt the second, and so on.

Unseal / Seal

Unseal

To decrypt an unseal key,

echo "whatever that was printed during init" | base64 --decode | gpg -dq

The output will be the decrypted key.

Then unseal vault,

vault operator unseal
# Enter decrypted key on prompt

Seal

vault operator seal

Enabling authentication

You can always login with a root token,

vault login <root-token>

But it is generally a bad idea to persist a root token.

Therefore, we instead enable different authentication methods to login to Vault.

The simplest auth method is userpass.

Enable userpass

# By default it is mounted to auth/userpass
vault auth enable userpass

# You can set your own path though
vault auth enable -path=my-path-here userpass

Before you enable any other auth methods, initially you’ll have to be logged in with your root token.

Then create a user by:

vault write auth/userpass/users/<username> \
  password=<password> \
  policies="list,of,policies,separated,by,comma"

You can now login with the created user:

vault login -method="userpass" username="<username>"

Policies

Create a policy

Create an .hcl file. The name is irrelevant.

Details of what goes into this file can be found here.

Add a policy

To add a policy:

vault policy write <policy-name> some-policy.hcl

References: