Heroku-Vault

This repository contains a minimal setup for deploying HashiCorp Vault to Heroku. It uses Terraform to provision and configure a single instance of a Vault server to run on a free Heroku dyno.

This deployment of Vault uses a Heroku Postgres instance as its backing storage and K/V Version 2 as its default secrets engine. It also includes auto-unsealing as a feature, enabled by vault-init. See its documentation as well as src/scripts/start.sh for more information on how this works.

This setup is not meant to be a production-ready deployment of Vault - it should only be used if you want to get Vault up and running in the shortest amount of time for basic or personal use cases.

Usage

Requirements

• terraform v0.14+
• vault-init v0.2+

You will also need a Heroku account and an associated API key for interacting with the Heroku API.

Deploy to Heroku

1. Change into the terraform/deployment directory:

   # from root of repository
   cd terraform/deployment

2. Ensure the following environment variables are set as required by the Terraform Heroku Provider:

   export HEROKU_EMAIL=<the email associated with your Heroku account>
   export HEROKU_API_KEY=<the API key associated with your Heroku account>

3. Create a secure 32-byte secret key required by vault-init for encrypting the root token and unseal keys generated by Vault during the initialization process.

   One option is to use OpenSSL:

   openssl rand -base64 24

   You should store this secret key somewhere safe for future use - you will need it to fetch and decrypt the data stored by vault-init.

4. Create a terraform.tfvars file with the following variables:

   # terraform/deployment/terraform.tfvars
   heroku_app = <name of the Heroku app>
   heroku_domain = <an optional custom domain for the Heroku app>
   vault_init_secret_key = <the 32-byte secret key>

5. Provision the Heroku resources and deploy the terraform/deployment/heroku-vault.tar.gz build (generated from src) to the newly created Heroku app:

   terraform apply

   The output should contain the URL of the Heroku app as well as the URL of its associated database.

6. Check the Vault UI to ensure that it is initialized and unsealed by visiting the app URL. You might need to wait a minute or two for this.

7. Use vault-init to fetch the Vault server's initial root token by passing in your secret key and the database URL:

   vault-init show \
      --encryption-local-secret-key [SECRET-KEY] \
      --storage-postgres-connection-url [DATABASE-URL]

   You do not need to store this root token as you can always retrieve it again using vault-init.

Configure Vault

The default configuration for Vault can be found in terraform/configuration/main.tf.

Features:

• Enables the file audit device.
• Enables the userpass and github auth methods.
• Mounts the kv-v2 secrets engine at a given path.
• Defines an admin policy that grants admin access to secrets under the given mount path.

To apply these configurations:

1. Change into the terraform/configuration directory:

   # from root of repository
   cd terraform/configuration

2. Ensure the following environment variables are set as required by the Terraform Vault Provider.

   export VAULT_ADDR=<the URL of the Heroku app>
   export VAULT_TOKEN=<the initial root token generated by Vault>

3. Create a terraform.tfvars file with the following variables:

   # terraform/configuration/terraform.tfvars
   mount_path          = <an optional mount path for the default secrets engine (default: "secret")>
   github_organisation = <an optional GitHub organisation used for authenticating against Vault (default: "")>
   admin_username      = <an optional username of the admin user to create (default: null)>
   admin_username      = <an optional password of the admin user to create (default: null)>

4. Configure the Vault server:

   terraform apply

Authentication

Userpass

If an admin username and password were provided, this admin user will be created under the userpass auth method. You should be able to access Vault using this username and password.

This user will be granted the admin policy, unless defined otherwise in the policies attribute of the vault_generic_endpoint.userpass_admin resource found in terraform/configuration/main.tf.

GitHub

If a GitHub organisation was provided for the github auth method, users belonging to this organisation should be able to access Vault via a GitHub personal access token with the read:org scope.

This user will be granted the admin policy, unless defined otherwise in the token_policies attribute of the vault_github_auth_backend.github resource found in terraform/configuration/main.tf.

Development

If you wish to tailor the setup to your own needs, have a look at the files in src/scripts and terraform and modify them accordingly.

A Docker Compose setup is provided to facilitate local testing of the files in src/scripts and terraform/configuration. To run the Docker Compose environment:

docker-compose up

If you have made any changes to the src folder, remember to regenerate terraform/deployment/heroku-vault.tar.gz before deploying Vault. You can use the given Makefile for this:

make terraform/deployment/heroku-vault.tar.gz