Vault

Installing

To install Vault follow the Vault installation instructions. If you have a Mac, you can install Vault using Homebrew. You can validate that you have it installed by running the following command.

vault -h

After Vault has been installed, the next step is to start up a Vault server.

vault server -dev

This will give you an output that looks like this:

==> Vault server configuration:

             Api Address: http://127.0.0.1:8200
                     Cgo: disabled
         Cluster Address: https://127.0.0.1:8201
              Listener 1: tcp (addr: "127.0.0.1:8200", cluster address: "127.0.0.1:8201", max_request_duration: "1m30s", max_request_size: "33554432", tls: "disabled")
               Log Level: info
                   Mlock: supported: false, enabled: false
           Recovery Mode: false
                 Storage: inmem
                 Version: Vault v1.4.2
             Version Sha: 18f1c494be8b06788c2fdda1a4296eb3c4b174ce+CHANGES

WARNING! dev mode is enabled! In this mode, Vault runs entirely in-memory
and starts unsealed with a single unseal key. The root token is already
authenticated to the CLI, so you can immediately begin using Vault.

You may need to set the following environment variable:

    $ export VAULT_ADDR='http://127.0.0.1:8200'

The unseal key and root token are displayed below in case you want to
seal/unseal the Vault or re-authenticate.

Unseal Key: <a long key>
Root Token: <a token>

Development mode should NOT be used in production installations!

Configuring

Once Vault is installed and running, the next step is to configure it to work with your application. Since we want multiple applications (in production) to be able to use the same Vault infrastructure, we control access with Vault policies and different key/value secret paths. In the following examples, VAULT_SECRET_NAMESPACE will be the secret path where your secrets are stored. This can be any string (except "secrets" since that exists by default) of your choosing, for example local-secrets. VAULT_POLICY_NAME will be the name of the policy that we use to control access to VAULT_SECRET_NAMESPACE. Once again, this should be a string. For example, local-policy.

To set up a policy and secret path run the following commands:

vault secrets enable -path=<VAULT_SECRET_NAMESPACE>/ kv-v2

vault policy write VAULT_POLICY_NAME -<<EOF
# grant permission to new VAULT_SECRET_NAMESPACE path
path "VAULT_SECRET_NAMESPACE/data/*" {
  capabilities = ["create", "update", "read"]
}
EOF

vault token create -policy=VAULT_POLICY_NAME

The final command will give you the following output:

# Key                  Value
# ---                  -----
# token                important-policy-token
# token_accessor       another-less-important-token
# token_duration       768h
# token_renewable      true
# token_policies       ["default" VAULT_POLICY_NAME]
# identity_policies    []
# policies             ["default" VAULT_POLICY_NAME]

The token output from above is what you will use in your application to access Vault. All that is left to do is set the appropriate ENV variables in your .env file.

export VAULT_TOKEN=important-policy-token export VAULT_SECRET_NAMESPACE=<your
namespace from above>

Restart your application to start using Vault. One easy way to see it in action is via the Rails console.

# Enabled Example
[3] pry(main)> AppSecrets["TEST_SET"]="success"
=> "success"
[4] pry(main)> AppSecrets["TEST_SET"]
=> "success"

# Disabled Example
[2] pry(main)> AppSecrets["TEST_SET"]="success"
Vault::MissingTokenError: Missing Vault token! I cannot make requests to Vault without a token. Please
set a Vault token in the client:

    Vault.token = "1234"

or authenticate with Vault using the Vault CLI:

    $ vault auth ...

or set the environment variable $VAULT_TOKEN to the token value:

    $ export VAULT_TOKEN="..."

Please refer to the documentation for more examples.