Configure HashiCorp Vault as a vault backend with certificate authentication

Before you can configure the Vault entity in Kong Gateway, you must configure HashiCorp Vault to authenticate clients based on certificates signed by the provided root CA certificate and store a secret.

Create configuration files

First, you need to create the primary configuration file config.hcl for HashiCorp Vault in the ./vault directory:

listener "tcp" {
  address     = "0.0.0.0:8200"
  tls_cert_file = "./vault/certs/vault.crt"
  tls_key_file  = "./vault/certs/vault.key"
}

storage "file" {
  path = "./vault/data"
}

ui = true

Then, create the HashiCorp policy file rw-secrets.hcl in the ./vault directory:

# Full access to everything — use with caution!
path "*" {
  capabilities = ["create", "read", "update", "delete", "list", "sudo"]
}

Configure the Vault and store a secret

Now, you can configure HashiCorp Vault to use certificate-based authentication.

1. Start HashiCorp Vault:

   vault server -config=./vault/config.hcl

   Copied!
2. In a new terminal, configure HashiCorp Vault to trust the TLS certificate:

   export VAULT_CACERT=$HOME/vault/certs/vault.crt

   Copied!
3. Initialize the Vault:

   vault operator init -key-shares=1 -key-threshold=1

   Copied!

   This will output your unseal key and your inital root token. Export them as environment variables:

   export HCV_UNSEAL_KEY='YOUR-UNSEAL-KEY'
   export DECK_HCV_TOKEN='YOUR-INITIAL-ROOT-TOKEN'

   Copied!
4. Unseal your Vault:

   vault operator unseal $HCV_UNSEAL_KEY

   Copied!
5. Login to your Vault:

   vault login $DECK_HCV_TOKEN

   Copied!
6. Write the policy to access secrets:

   vault policy write rw-secrets ./vault/rw-secrets.hcl

   Copied!
7. Enable cert-based authentication:

   vault auth enable cert

   Copied!
8. Configure Vault to authenticate clients based on certificates signed by the provided root CA certificate:

   vault write auth/cert/config certificate=./vault/certs/rootCA.crt

   Copied!
9. Register and bind the certificate to the rw-secrets policy:

   vault write auth/cert/certs/gw311 \
      display_name="gw311" \
      policies="rw-secrets" \
      certificate=@./vault/certs/rootCA.crt \
      allow_subdomains=false

   Copied!
10. Test the login using certificate authentication:

    vault login -method=cert \
      -client-cert=./vault/certs/kong.example.com.crt \
      -client-key=./vault/certs/kong.example.com.key

    Copied!
11. Enable the K/V secrets engine:

    vault secrets enable -path=kong kv

    Copied!
12. Create a secret:

    vault kv put kong/headers/request header="x-kong:test"

    Copied!
13. Confirm you can retrieve the secret through Vault:

    vault kv get kong/headers/request

    Copied!

Because the certificates in this tutorial are self-signed, we must configure the lua_ssl_trusted_certificate parameter in kong.conf to use the certificate that is served from HashiCorp Vault, vault.crt.

1. In terminal, copy your vault.crt file to your Docker container:

    docker cp ./vault/certs/vault.crt kong-quickstart-gateway:./vault.crt

   Copied!
2. In your Docker container, make a copy of the default Kong configuration file:

    cp /etc/kong/kong.conf.default /etc/kong/kong.conf

   Copied!
3. Open kong.conf in your Docker container, find lua_ssl_trusted_certificate, uncomment it and replace it with the following:

    lua_ssl_trusted_certificate = ./vault.crt

   Copied!
4. Reload Kong Gateway in your Docker container to get the setting to take effect:

    kong reload -c /etc/kong/kong.conf

   Copied!

Export the following environment variables:

export DECK_HCV_HOST=host.docker.internal
export DECK_HCV_CERT_KEY=$(awk 'NR > 1 {printf "\\n"} {printf "%s", $0} END {printf ""}' ./vault/certs/kong.example.com.key)
export DECK_HCV_CERT=$(awk 'NR > 1 {printf "\\n"} {printf "%s", $0} END {printf ""}' ./vault/certs/kong.example.com.crt)

In this tutorial, we’re using host.docker.internal as our host instead of the localhost variable that HashiCorp Vault is using. This is because if you used the quickstart script, Kong Gateway is running in a container and uses a different localhost.

Using decK, create a Vault entity in the kong.yaml file with the required parameters for HashiCorp Vault:

echo '
_format_version: "3.0"
vaults:
  - name: hcv
    prefix: hashicorp-vault
    description: Storing secrets in HashiCorp Vault
    config:
      host: "${{ env "DECK_HCV_HOST" }}"
      token: "${{ env "DECK_HCV_TOKEN" }}"
      kv: v1
      mount: kong
      port: 8200
      protocol: https
      auth_method: cert
      cert_auth_cert_key: "${{ env "DECK_HCV_CERT_KEY" }}"
      cert_auth_cert: "${{ env "DECK_HCV_CERT" }}"
' | deck gateway apply -

To validate that the secret was stored correctly in HashiCorp Vault, you can call a secret from your vault using the kong vault get command within the Data Plane container.

docker exec kong-quickstart-gateway kong vault get {vault://hashicorp-vault/headers/request/header}

If the vault was configured correctly, this command should return the value of the secret. You can use {vault://hashicorp-vault/headers/request/header} to reference the secret in any referenceable field.

For more information about supported secret types, see What can be stored as a secret.