Setup Hashicorp Vault KMS service

Hashicorp Vault (Vault) is a clusterable secure secret storage and management service.

(Dev) Vault dev server

You can test embedded with a local vault dev server (in-memory setup and storage).

brew tap hashicorp/tap
brew install hashicorp/tap/vault

vault server -dev -dev-root-token-id root

export VAULT_ADDR=http://127.0.0.1:8200

Enter http://127.0.0.1:8200/ui in the browser address bar. (Use above dev-root-token-id)

(Production) Vault KMS deployment

Use the Vault cloud or setup and deploy a persistent Vault service. See: Hashicorp Vault Deployment We recommend setting up HTTPS/TLS certificates in addition to this base configuration. See: Medium enable vault HTTPS

echo 'storage "raft" {
  path    = "./vault/data"
  node_id = "node1"
}

listener "tcp" {
  address     = "127.0.0.1:8200"
  tls_disable = "true"
}

disable_mlock = true

api_addr = "http://127.0.0.1:8200"
cluster_addr = "https://127.0.0.1:8201"
ui = true' > vault_config.hcl

# start server
vault server -config=vault_config.hcl

# init server (e.g.: 1 replica)
vault operator init -n 1 -t 1

# unseal
vault operator unseal

# logon once to start server
vault logon

# enable transit
vault secrets enable transit

Authenticate with Token

Embedded Helm Chart

When running Embedded via the Synqly Embedded Helm Chart, set the following values in values.yaml in order to allow embedded to authenticate with Hashicorp Vault using a Token:

global:
  ...
  encryptionKey:
    ...
    hashicorpVault:
      enabled: true
      vaultURL: <vault-instance-url:port>
      secretsEnginePath: "transit/"
      auth:
        token:
          enabled: true
          tokenValue: <token>

Embedded Command Line

Add the following CLI parameters to use Hashicorp Vault as the KMS store when running embedded on the command line.

embedded --kms-type=vault --kms-vault-address="http://127.0.0.1:8200" \
  --kms-vault-mount="transit/" \
  --kms-vault-token="hvs.gCNPmjbs..." \
  ...

Authenticate with AppRole

Configure App Role Authentication

In order to authenticate with Hashicorp Vault using AppRole, we first need to configure the Vault instance to allow AppRole authentication and create a role for embedded to use.

The following steps are based on Hashicorp's Use AppRole Authentication.

Enable App Role Authentication

In the Vault UI:

  1. Navigate to Access -> Authentication Methods -> Enable new method.
  2. Select "AppRole"
  3. Use the default "approle" Path
  4. Click "Enable method"

Create ACL Policy

In the Vault UI, navigate to Policies -> Create ACL Policy. Create a policy with the following permissions. For the purposes of this example, we will name it synqly-secret-access:

# Grant Embedded permission to access KMS secrets in `transit` engine
path "transit/*" {
  capabilities = [ "create", "read", "update", "delete", "list" ]
}

Create App Role

The following commands can be run using the vault CLI tool for a local instance, or the Vault Web REPL for hosted Vault instances.

Run the following command to create an App Role with access to the previously defined ACL policy:

### Format
vault write auth/approle/role/<role-name> token_policies="<acl-policy-name>" token_ttl=1h token_max_ttl=4h

### Example
vault write auth/approle/role/synqly token_policies="synqly-secret-access" token_ttl=1h token_max_ttl=4h

Next, run the following command to retrieve the ID of the new role:

### Format
vault read auth/approle/role/<role-name>/role-id

### Example
vault read auth/approle/role/synqly/role-id

Expected Response:

Key     Value
role_id db02de05-fa39-4855-059b-67221c5c2f63

Finally, run the following command to generate a secret token for the new role:

### Format
vault write -force auth/approle/role/<role-name>/secret-id

### Example
vault write -force auth/approle/role/synqly/secret-id

Expected Response:

secret_id               6a174c20-f6de-a53c-74d2-6018fcceff64
secret_id_accessor      c454f7e5-996e-7230-6074-6ef26b7bcf86
secret_id_ttl           10m
secret_id_num_uses      40

Save the role_id and secret_id, they will be needed for embedded to authenticate using the new role.

Embedded Helm Chart

When running Embedded via the Synqly Embedded Helm Chart, set the following values in values.yaml in order to allow embedded to authenticate with Hashicorp Vault using AppRole authentication.

global:
  ...
  encryptionKey:
    ...
    hashicorpVault:
      enabled: true
      vaultURL: <vault-instance-url:port>
      secretsEnginePath: "transit/"
      auth:
        ...
        appRole:
          enabled: true
          roleId: <role-id-from-vault-cli>
          secretId: <secret-id-from-vault-cli>

Embedded CLI

Add the following CLI parameters to use Hashicorp Vault as the KMS store when running embedded on the command line.

embedded --kms-type=vault --kms-vault-address="http://127.0.0.1:8200" \
  --kms-vault-mount="transit/" \
  --kms-vault-role-id=<role-id-from-vault-cli> \
  ---kms-vault-secret-id=<secret-id-from-vault-cli> \
  ...