Locked Shut

Of course, another important feature of Vault is authenticating so that you can interact with the stored data. A dev server automatically allows you straight into the locked vault, but usually you would need to authenticate, for obvious reasons.

The need to authenticate translates into Vault creating a token for access. In the dev server's start-up output, you saw the root token being created so you could interact. The root token is how you'd set up Vault initially under normal circumstances. The eagle-eyed among you will see that the command

$ vault token create
Key                  Value
---                  -----
token                s.1xnAreJvUEKnKwKs1KVtcNyQ
token_accessor       DulIsR7BVxv6k4YF6JoMagb0
token_duration       ?
token_renewable      false
token_policies       ["root"]
identity_policies    []
policies             ["root"]

creates a child token. The parent-child design means that, because tokens always have a parent token, if that parent is revoked, then all child tokens under it will also be revoked. Note that the child token above inherits the root token permissions, as shown by the token_policies line.

Once you've created a token like that, it's possible to log in as in Listing 4. Study the output carefully. As you can see, "Future Vault requests will automatically use this token," so there's no need to log in repeatedly to Vault. The time to live (TTL) or token_duration symbol is shown as a lemniscate (i.e., infinity symbol), meaning it won't expire.

$ vault login s.1xnAreJvUEKnKwKs1KVtcNyQ
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                s.1xnAreJvUEKnKwKs1KVtcNyQ
token_accessor       DulIsR7BVxv6k4YF6JoMagb0
token_duration       ?
token_renewable      false
token_policies       ["root"]
identity_policies    []
policies             ["root"]

Running the command

$ vault revoke s.1xnAreJvUEKnKwKs1KVtcNyQ

revokes the same child token just created.

Turn the Key

Obviously, you also need to make sure you can change a child token's policies to refine the access that token is allowed.

Policies in Vault use HashiCorp's intuitive HashiCorp Configuration Language (HCL) [7] – or JSON otherwise. The policy example in the Vault docs looks something like:

path "secret/data/*" {
  capabilities = ["create", "update"]
}

Here, the path secret/data and everything within it (denoted by the asterisk) can be changed (update) by that policy, and new information can be written (create). However, if you added this to the following policy, what would happen?

path "secret/data/chrisbinnie" {
  capabilities = ["read"]
}

Although you'd still be able to write and change data under the path secret/data, you would not be able to do so in secret/data/chrisbinnie, which only allows you to read from it.

A top tip is to use the fmt formatting command when writing policies (HashiCorp's Terraform has this ability, too) to get feedback on typos and formatting issues. If I add the two path snippets above to a file called lab-policy.hcl and check it with the fmt command,

$ vault policy fmt lab-policy.hcl

a happy policy will output:

Success! Formatted policy: lab-policy.hcl

The next step is to upload the policy to Vault (just a write to storage, really) with a name:

$ vault policy write lab-policy lab-policy.hcl
Success! Uploaded policy: lab-policy

Here, I've called the policy lab-policy, which I'll reference again in a moment.

If I want to list the policies currently stored in Vault, I'd use the command:

$ vault policy list
lab-policy
default
root

It looks like the previous policy upload command worked as hoped. To check inside a policy, you can use the view command:

$ vault policy read lab-policy
path "secret/data/*" {
  capabilities = ["create", "update"]
}
path "secret/data/chrisbinnie" {
  capabilities = ["read"]
}

To continue, you create an auth method. According to the docs [8], these methods are "components in Vault that perform authentication and are responsible for assigning identity and a set of policies to a user."

The auth prefix is used for authentication methods just as secrets has its own prefix, and authentication follows the same philosophy when it comes to referring to it by path. Look at this command which uses the userpass plugin:

$ vault auth enable userpass
Success! Enabled userpass auth method at: userpass/

Here, I'm enabling userpass as the name of the auth method. Now, I'll create a user with a password and attach the policy lab-policy to the user:

$ vault write auth/userpass/users/chris password="nothingtoseehere" policies="lab-policy"
Success! Data written to: auth/userpass/users/chris

This command is working under the userpass auth method and under the path users/chris while adding a password and a policy to the user.

Now I log back in as chris :

$ vault login -method=userpass username=chris password=nothingtoseehere

Listing 5 shows the results. Armed with the correct commands, it's now possible to limit the access rights of a user very effectively. You can see that both default and lab-policy are attached to the username under token_policies. Now the token generated by that vault login command can be used to access Vault as required.

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                  s.PWHPg5hvBYnxkFHOyC1ZgoRu
token_accessor         DRBFdwUjwQd8UgfZbE1XxmBt
token_duration         768h
token_renewable        true
token_policies         ["default" "lab-policy"]
identity_policies      []
policies               ["default" "lab-policy"]
token_meta_username    chris

Once you have the concepts and basics under your belt, you can read further about internal groups and external groups [9] to assist with multiple users. If you visit the web page in a fully fledged browser and click Show Tutorial at the bottom, a nice browser-friendly shell window pops up so you can run shell commands yourself (Figure 1). That functionality is powered by the truly excellent Katacoda [10], which is definitely worth a visit if you've never used their Live environments in a browser before. For example, I use it for Kubernetes testing sometimes.

Figure 1: The docs page has a handy shell window to test Vault in your browser.

The End Is Nigh

A highly secure, trusted place to keep your secrets and certificates is an invaluable addition to any estate. A common way to interact with and manipulate the Vault API is with the curl command, which I hope should now make sense.

If you get stuck, you can try the autocompletion feature mentioned earlier and run the command

$ vault kv help

for assistance. I'm sure you'll find the docs and the built-in CLI help very clear and readable.

Once you're comfortable with how the innards of Vault work, the next thing to do is configure HA in a cloud environment (e.g., AWS) so that it will play nicely with software like Kubernetes.

For HA, you need a suitable back end to avoid locking headaches from multiple users or applications trying to write to the same bit of stored data at the same time. You have quite a few solutions from which to choose, such as Consul [11] (included with Vault Enterprise and also made by HashiCorp) or DynamoDB from AWS.

A nice article on the AWS site [12] can get you going. Because Vault is so popular, you'll find lots of useful online literature to help out if you get stuck.

One thing that I didn't covered in this article is the useful browser-based user interface (UI), which is a nice, clean, and simple way of interacting with Vault. When you have a more mature installation of Vault up and running, be certain to have a rummage around the UI.