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:
- Navigate to Access -> Authentication Methods -> Enable new method.
- Select "AppRole"
- Use the default "approle" Path
- 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> \
...