# 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](https://developer.hashicorp.com/vault/tutorials/getting-started/getting-started-deploy)
We recommend setting up HTTPS/TLS certificates in addition to this base configuration.
See: [Medium enable vault HTTPS](https://medium.com/@java.developer.raman/enable-vault-to-be-accessible-via-https-b725cf71b719)


```
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:


```yaml
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](https://developer.hashicorp.com/vault/docs/auth/approle).

### 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`:


```hcl
# 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:


```bash
### 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:


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

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

Expected Response:


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

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


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

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

Expected Response:


```bash
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.


```yaml
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> \
  ...
```