You are browsing unreleased documentation. See the latest documentation here.

HashiCorp Vault

HashiCorp Vault can be configured with environment variables or with a Vault entity.

Configuration via environment variables

Configure the following environment variables on your Kong Gateway data plane:

Static Vault token authentication:

export KONG_VAULT_HCV_PROTOCOL=<protocol(http|https)>
export KONG_VAULT_HCV_HOST=<hostname>
export KONG_VAULT_HCV_PORT=<portnumber>
export KONG_VAULT_HCV_MOUNT=<mountpoint>
export KONG_VAULT_HCV_KV=<v1|v2>
export KONG_VAULT_HCV_AUTH_METHOD=token
export KONG_VAULT_HCV_TOKEN=<tokenstring>

Kubernetes service account role authentication:

export KONG_VAULT_HCV_PROTOCOL=<protocol(http|https)>
export KONG_VAULT_HCV_HOST=<hostname>
export KONG_VAULT_HCV_PORT=<portnumber>
export KONG_VAULT_HCV_MOUNT=<mountpoint>
export KONG_VAULT_HCV_KV=<v1|v2>
export KONG_VAULT_HCV_AUTH_METHOD=kubernetes
export KONG_VAULT_HCV_KUBE_ROLE=<rolename>

HashiCorp Vault AppRole authentication:

export KONG_VAULT_HCV_PROTOCOL=<protocol(http|https)>
export KONG_VAULT_HCV_HOST=<hostname>
export KONG_VAULT_HCV_PORT=<portnumber>
export KONG_VAULT_HCV_MOUNT=<mountpoint>
export KONG_VAULT_HCV_KV=<v1|v2>
export KONG_VAULT_HCV_AUTH_METHOD=approle
export KONG_VAULT_HCV_APPROLE_ROLE_ID=<role_id>
export KONG_VAULT_HCV_APPROLE_SECRET_ID=<secret_id>

You can also store this information in an entity.

Configuration via vaults entity

The Vault entity can only be used once the database is initialized. Secrets for values that are used before the database is initialized can’t make use of the Vaults entity.

curl -i -X PUT http://HOSTNAME:8001/vaults/hashicorp-vault \
  --data name="hcv" \
  --data description="Storing secrets in HashiCorp Vault" \
  --data config.protocol="https" \
  --data config.host="localhost" \
  --data config.port="8200" \
  --data config.mount="secret" \
  --data config.kv="v2" \
  --data config.token="<token>"

{
    "config": {
        "host": "localhost",
        "kv": "v2",
        "mount": "secret",
        "port": 8200,
        "protocol": "https",
        "token": "<token>"
    },
    "created_at": 1645008893,
    "description": "Storing secrets in HashiCorp Vault",
    "id": "0b43d867-05db-4bed-8aed-0fccb6667837",
    "name": "hcv",
    "prefix": "hashicorp-vault",
    "tags": null,
    "updated_at": 1645008893
}

_format_version: "3.0"
vaults:
- config:
    host: localhost
    kv: v2
    mount: secret
    port: 8200
    protocol: https
    token: <token>
  description: Storing secrets in HashiCorp Vault
  name: hcv
  prefix: hashicorp-vault

Examples

For example, if you’ve configured a HashiCorp Vault with a path of secret/hello and a key=value pair of foo=world:

vault kv put secret/hello foo=world

Key                Value
---                -----
created_time       2022-01-15T01:40:03.740833Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            1

Access these secrets like this:

{vault://hcv/hello/foo}

Or, if you configured an entity:

{vault://hashicorp-vault/hello/foo}

If you have configured a secret value in multiple versions:

# Requires kv2 engine enabled
vault kv patch secret/hello foo=world2

======= Metadata =======
Key                Value
---                -----
created_time       2022-01-16T01:40:03.740833Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            2

Access an older version of the secret like this:

# For version 1
{vault://hcv/hello/foo#1}

# For version 2
{vault://hcv/hello/foo#2}

# Do not specify version number for the latest version
{vault://hcv/hello/foo}

How does Kong retrieve secrets from HashiCorp Vault?

Kong 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 authenticates to HashiCorp Vault using one of the following methods:

• If you’re using the token auth method, Kong uses the config.token as the client token.
• If you’re using the kubernetes auth method, Kong 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. The request looks like the following:

POST /v1/auth/<config.kube_auth_path>/login
Host: <config.host>:<config.port>
Content-Type: application/json
X-Vault-Namespace: <config.namespace>

{
  "jwt": "<service account JWT token>",
  "role": "<config.kube_role>"
}

• If you’re using the approle auth method, Kong 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 will call the unwrap API /v1/sys/wrapping/unwrap to unwrap the response wrapping token to fetch the real secret ID. Kong 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. The request looks like the following:

POST /v1/auth/<config.approle_auth_path>/login
Host: <config.host>:<config.port>
Content-Type: application/json
X-Vault-Namespace: <config.namespace>

{
  "role_id": "<config.approle_role_id>",
  "secret_id": "<secret id>"
}

By calling the login API, Kong 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 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:

GET /v1/<config.mount>/<secret path>
Host: <config.host>:<config.port>
X-Vault-Token: <client token>
X-Vault-Namespace: <config.namespace>

GET /v1/<config.mount>/data/<secret path>
Host: <config.host>:<config.port>
X-Vault-Token: <client token>
X-Vault-Namespace: <config.namespace>

GET /v1/<config.mount>/data/<secret path>?version=<version>
Host: <config.host>:<config.port>
X-Vault-Token: <client token>
X-Vault-Namespace: <config.namespace>

Warning: Make sure you’ve configured the correct KV engine version in config.kv, otherwise Kong will fail to parse the response.

Kong will parse the response of the read secret API automatically and return the secret value.

Vault configuration options

Use the following configuration options to configure the vaults entity through any of the supported tools:

• Admin API
• Declarative configuration
• Kong Manager
• Konnect

Configuration options for a HashiCorp vault in Kong Gateway:

Common options: