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:

  1. export KONG_VAULT_HCV_PROTOCOL=<protocol(http|https)>
  2. export KONG_VAULT_HCV_HOST=<hostname>
  3. export KONG_VAULT_HCV_PORT=<portnumber>
  4. export KONG_VAULT_HCV_MOUNT=<mountpoint>
  5. export KONG_VAULT_HCV_KV=<v1|v2>
  6. export KONG_VAULT_HCV_AUTH_METHOD=token
  7. export KONG_VAULT_HCV_TOKEN=<tokenstring>

Kubernetes service account role authentication:

  1. export KONG_VAULT_HCV_PROTOCOL=<protocol(http|https)>
  2. export KONG_VAULT_HCV_HOST=<hostname>
  3. export KONG_VAULT_HCV_PORT=<portnumber>
  4. export KONG_VAULT_HCV_MOUNT=<mountpoint>
  5. export KONG_VAULT_HCV_KV=<v1|v2>
  6. export KONG_VAULT_HCV_AUTH_METHOD=kubernetes
  7. export KONG_VAULT_HCV_KUBE_ROLE=<rolename>

HashiCorp Vault AppRole authentication:

  1. export KONG_VAULT_HCV_PROTOCOL=<protocol(http|https)>
  2. export KONG_VAULT_HCV_HOST=<hostname>
  3. export KONG_VAULT_HCV_PORT=<portnumber>
  4. export KONG_VAULT_HCV_MOUNT=<mountpoint>
  5. export KONG_VAULT_HCV_KV=<v1|v2>
  6. export KONG_VAULT_HCV_AUTH_METHOD=approle
  7. export KONG_VAULT_HCV_APPROLE_ROLE_ID=<role_id>
  8. 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.

Admin API

Declarative configuration

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

Result:

  1. {
  2. "config": {
  3. "host": "localhost",
  4. "kv": "v2",
  5. "mount": "secret",
  6. "port": 8200,
  7. "protocol": "https",
  8. "token": "<token>"
  9. },
  10. "created_at": 1645008893,
  11. "description": "Storing secrets in HashiCorp Vault",
  12. "id": "0b43d867-05db-4bed-8aed-0fccb6667837",
  13. "name": "hcv",
  14. "prefix": "hashicorp-vault",
  15. "tags": null,
  16. "updated_at": 1645008893
  17. }

Secrets management is supported in decK 1.16 and later.

Add the following snippet to your declarative configuration file:

  1. _format_version: "3.0"
  2. vaults:
  3. - config:
  4. host: localhost
  5. kv: v2
  6. mount: secret
  7. port: 8200
  8. protocol: https
  9. token: <token>
  10. description: Storing secrets in HashiCorp Vault
  11. name: hcv
  12. 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:

  1. vault kv put secret/hello foo=world
  2. Key Value
  3. --- -----
  4. created_time 2022-01-15T01:40:03.740833Z
  5. custom_metadata <nil>
  6. deletion_time n/a
  7. destroyed false
  8. version 1

Access these secrets like this:

  1. {vault://hcv/hello/foo}

Or, if you configured an entity:

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

If you have configured a secret value in multiple versions:

  1. # Requires kv2 engine enabled
  2. vault kv patch secret/hello foo=world2
  3. ======= Metadata =======
  4. Key Value
  5. --- -----
  6. created_time 2022-01-16T01:40:03.740833Z
  7. custom_metadata <nil>
  8. deletion_time n/a
  9. destroyed false
  10. version 2

Access an older version of the secret like this:

  1. # For version 1
  2. {vault://hcv/hello/foo#1}
  3. # For version 2
  4. {vault://hcv/hello/foo#2}
  5. # Do not specify version number for the latest version
  6. {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:
  1. POST /v1/auth/<config.kube_auth_path>/login
  2. Host: <config.host>:<config.port>
  3. Content-Type: application/json
  4. X-Vault-Namespace: <config.namespace>
  5. {
  6. "jwt": "<service account JWT token>",
  7. "role": "<config.kube_role>"
  8. }
  • 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:
  1. POST /v1/auth/<config.approle_auth_path>/login
  2. Host: <config.host>:<config.port>
  3. Content-Type: application/json
  4. X-Vault-Namespace: <config.namespace>
  5. {
  6. "role_id": "<config.approle_role_id>",
  7. "secret_id": "<secret id>"
  8. }

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:

KV v1

KV v2

KV v2 with versioned secrets

  1. GET /v1/<config.mount>/<secret path>
  2. Host: <config.host>:<config.port>
  3. X-Vault-Token: <client token>
  4. X-Vault-Namespace: <config.namespace>
  1. GET /v1/<config.mount>/data/<secret path>
  2. Host: <config.host>:<config.port>
  3. X-Vault-Token: <client token>
  4. X-Vault-Namespace: <config.namespace>
  1. GET /v1/<config.mount>/data/<secret path>?version=<version>
  2. Host: <config.host>:<config.port>
  3. X-Vault-Token: <client token>
  4. 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:

ParameterField name {:width=25%:}Description
vaults.config.protocolconfig-protocol (Kong Manager)
Protocol (Konnect)
The protocol to connect with. Accepts one of http or https.
vaults.config.hostconfig-host (Kong Manager)
Host (Konnect)
The hostname of your HashiCorp vault.
vaults.config.portconfig-port (Kong Manager)
Port (Konnect)
The port number of your HashiCorp vault.
vaults.config.mountconfig-mount (Kong Manager)
Mount (Konnect)
The mount point.
vaults.config.kvconfig-kv (Kong Manager)
Kv (Konnect)
The secrets engine version. Accepts v1 or v2.
vaults.config.tokenconfig-token (Kong Manager)
Token (Konnect)
A token string.
vaults.config.ttlTTLTime-to-live (in seconds) of a secret from the vault when it’s cached. The special value of 0 means “no rotation” and it’s the default. When using non-zero values, it is recommended that they’re at least 1 minute.
vaults.config.neg_ttlNegative TTLTime-to-live (in seconds) of a vault miss (no secret). Negatively cached secrets will remain valid until neg_ttl is reached, after which Kong will attempt to refresh the secret again. The default value for neg_ttl is 0, meaning no negative caching occurs.
vaults.config.resurrect_ttlResurrect TTLTime (in seconds) for how long secrets will remain in use after they are expired (config.ttl is over). This is useful when a vault becomes unreachable, or when a secret is deleted from the Vault and isn’t replaced immediately. On this both cases, the Gateway will keep trying to refresh the secret for resurrect_ttl seconds. After that, it will stop trying to refresh. We recommend assigning a sufficiently high value to this configuration option to ensure a seamless transition in case there are unexpected issues with the Vault. The default value for resurrect_ttl is 1e8 seconds, which is about 3 years.
vaults.config.namespacenamespaceNamespace for the Vault. Vault Enterprise requires a namespace to successfully connect to it.
vaults.config.auth_methodauth-methodDefines the authentication mechanism when connecting to the HashiCorp Vault service. Accepted values are: token, kubernetes or approle.
vaults.config.kube_rolekube-roleDefines the HashiCorp Vault role for the Kubernetes service account of the running pod. keyring_vault_auth_method must be set to kubernetes for this to activate.
vaults.config.kube_api_token_filekube-api-token-fileDefines the file path for the Kubernetes service account token. If not specified then a default path /run/secrets/kubernetes.io/serviceaccount/token will be used.
vaults.config.kube_auth_pathkube-auth-pathDefines the path that activates the Kubernetes authentication method. If not specified, the default path kubernetes is used. Any single leading or trailing slash in the value will be automatically trimmed.
vaults.config.approle_auth_pathapprole_auth_pathSpecifies the path that activates the AppRole authentication method. If not provided, the default path AppRole will be used. Any single leading or trailing slash in the value will be automatically trimmed.
vaults.config.approle_role_idapprole_role_idSpecifies the role ID of the AppRole in HashiCorp Vault.
vaults.config.approle_secret_idapprole_secret_idDefines the secret ID of the AppRole in HashiCorp Vault.
vaults.config.approle_secret_id_fileapprole_secret_id_fileDefines the file path containing the secret ID value.
vaults.config.approle_response_wrappingapprole_response_wrappingDetermines whether the secret_id configured in the vault entity or secret id file is actually a response wrapping token. By default, it is set to false. When set to true, Kong will attempt to unwrap the response wrapping token to retrieve the actual secret id of the AppRole. Note: A response wrapping token can only be unwrapped once. Therefore, ensure that individual tokens are distributed to each Kong node in a typical cluster.

Common options:

ParameterField nameDescription
vaults.description
optional
DescriptionAn optional description for your vault.
vaults.nameNameThe type of vault. Accepts one of: env, gcp, aws, or hcv. Set hcv for HashiCorp Vault.
vaults.prefixPrefixThe reference prefix. You need this prefix to access secrets stored in this vault. For example, {vault://hcv-vault/<some-secret>}.