Home / How-to Guides
Edit
Report

Store Keyring data in a HashiCorp Vault

Uses: Kong Gateway
Incompatible with
konnect
Related Documentation
Gateway Documentation
Tags
#secrets-management #hashicorp-vault
Related Resources
Keyring
Configure HashiCorp Vault as a vault backend
HashiCorp Vault configuration parameters
Minimum Version
Kong Gateway - 3.4
TL;DR

Create a HashiCorp Vault and add a key and ID, then set the kong_keyring_strategy kong.conf parameter to vault and the required keyring_vault_* parameters in your configuration, either in kong.conf or with environment variables. Use the /keyring/vault/sync API to synchronize.

Prerequisites

HashiCorp Vault

This how-to requires you to have a dev mode or self-managed HashiCorp Vault. The following instructions will guide you through configuring a HashiCorp Vault in dev mode with the resources you need to integrate it with Kong Gateway.

Important: This tutorial uses the literal root string as your token, which should only be used in testing and development environments.

  1. Install HashiCorp Vault.
  2. In a terminal, start your Vault dev server with root as your token. 
    vault server -dev -dev-root-token-id root
  3. In the output from the previous command, copy the VAULT_ADDR to export.
  4. In a new terminal window, export your VAULT_ADDR as an environment variable.
  5. Verify that your Vault is running correctly: 
    vault status
  6. Authenticate with Vault: 
    vault login root
  7. Verify that you are using the v2 secrets engine: 
    vault read sys/mounts/secret

    The options key should have the map[version:2] value.

Create a key in the HashiCorp Vault

The Keyring integration with HashiCorp Vaults allows you to store and version Keyring data. Kong Gateway nodes can read the keys directly from the Vault to encrypt and decrypt sensitive data.

First, we need to add a key and key ID to the Vault. Let’s create a secret named keyring:

vault kv put -mount secret keyring id="8zgITLQh" key="t6NWgbj3g9cbNVC3/D6oZ2Md1Br5gWtRrqb1T2FZy44="

Set environment variables

Set the environment variables that will be used by Kong Gateway to enable the Keyring and connect it to the HashiCorp Vault. Since the Keyring feature requires a Kong Gateway Enterprise license, make sure to include it in the environment too.

export KONG_LICENSE_DATA="LICENSE-CONTENTS-GO-HERE"
export KONG_KEYRING_ENABLED="on"
export KONG_KEYRING_STRATEGY="vault"
export KONG_KEYRING_VAULT_HOST="http://host.docker.internal:8200"
export KONG_KEYRING_VAULT_MOUNT="secret"
export KONG_KEYRING_VAULT_PATH="keyring"
export KONG_KEYRING_VAULT_AUTH_METHOD="token"
export KONG_KEYRING_VAULT_TOKEN="root"

Start Kong Gateway

Create the Kong Gateway container with the environment variables. In this example, we can use the quickstart:

curl -Ls https://get.konghq.com/quickstart | bash -s -- -e KONG_LICENSE_DATA \
    -e KONG_KEYRING_ENABLED \
    -e KONG_KEYRING_STRATEGY \
    -e KONG_KEYRING_VAULT_HOST \
    -e KONG_KEYRING_VAULT_MOUNT  \
    -e KONG_KEYRING_VAULT_PATH \
    -e KONG_KEYRING_VAULT_AUTH_METHOD  \
    -e KONG_KEYRING_VAULT_TOKEN

Synchronize the Vault with the Keyring

Once the container is created, use the following command to sync the Keyring data from the HashiCorp Vault to the Kong Gateway Keyring.

curl -i -X POST http://localhost:8001/keyring/vault/sync

Validate

Check that the Keyring contains the key that we created in the HashiCorp Vault:

curl -i http://localhost:8001/keyring

The response should contain the ID of the key we created:

{
   "ids":[
      "8zgITLQh"
   ],
   "active":"8zgITLQh"
}

Cleanup

Clean up HashiCorp Vault

Stop the HashiCorp Vault dev server process by running the following:

pkill vault

Unset environment variables:

unset VAULT_ADDR

Destroy the Kong Gateway container

 
curl -Ls https://get.konghq.com/quickstart | bash -s -- -d

FAQs

How do I rotate my secrets in HashiCorp Vault and how does Kong Gateway pick up the new secret values?

You can rotate your secret in HashiCorp Vault by creating a new secret version with the updated value. You’ll also want to configure the ttl settings in your Kong Gateway Vault entity so that Kong Gateway pulls the rotated secret periodically.

How does Kong Gateway retrieve secrets from HashiCorp Vault?

Kong Gateway retrieves secrets from HashiCorp Vault’s HTTP API through a two-step process: authentication and secret retrieval.

Step 1: Authentication

Depending on the authentication method defined in config.auth_method, Kong Gateway authenticates to HashiCorp Vault using one of the following methods:

  • If you’re using the token auth method, Kong Gateway uses the config.token as the client token.
  • If you’re using the kubernetes auth method, Kong Gateway uses the service account JWT token mounted in the pod (path defined in the config.kube_api_token_file) to call the login API for the Kubernetes auth path on the HashiCorp Vault server and retrieve a client token.
  • v3.4+ If you’re using the approle auth method, Kong Gateway uses the AppRole credentials to retrieve a client token. The AppRole role ID is configured by field config.approle_role_id, and the secret ID is configured by field config.approle_secret_id or config.approle_secret_id_file.
    • If you set config.approle_response_wrapping to true, then the secret ID configured by config.approle_secret_id or config.approle_secret_id_file will be a response wrapping token, and Kong Gateway will call the unwrap API /v1/sys/wrapping/unwrap to unwrap the response wrapping token to fetch the real secret ID. Kong Gateway will use the AppRole role ID and secret ID to call the login API for the AppRole auth path on the HashiCorp Vault server and retrieve a client token.

By calling the login API, Kong Gateway will retrieve a client token and then use it in the next step as the value of X-Vault-Token header to retrieve a secret.

Step 2: Retrieving the secret

Kong Gateway uses the client token retrieved in the authentication step to call the Read Secret API and retrieve the secret value. The request varies depending on the secrets engine version you’re using. Kong Gateway will parse the response of the read secret API automatically and return the secret value.

Next Steps

Review the Vaults entity
Something wrong?
Report an Issue | Edit this Page

Help us make these docs great!

Kong Developer docs are open source. If you find these useful and want to make them better, contribute today!
Contribute

Still need help

Ask in our Forum
Contact Support