HashiCorp Vault

Uses: Kong Gateway Admin API deck KIC Konnect API Terraform

HashiCorp Vault cloud authentication

Kong Gateway Enterprise integrates with HashiCorp Vault as a secrets backend for storing and managing sensitive data such as certificates, API keys, and other credentials. To securely connect to a HashiCorp Vault instance, Kong Gateway Enterprise supports multiple authentication methods across generic, infrastructure, and cloud categories.

You can use both internal and external authentication methods depending on your environment. Internal authentication methods handle authentication entirely within HashiCorp Vault using credentials specific to Vault itself, such as a Vault token or an AppRole. External authentication relies on an identity managed by an external provider or infrastructure platform, such as Kubernetes, AWS IAM, or Azure Microsoft Entra ID. Authentication via a cloud provider uses JWT authentication. For details on which specific cloud IAM authentication mechanisms are supported, see the cloud provider support matrix.

Supported authentication methods

The following table describes which authentication methods are supported for HashiCorp Vault:

Method	Description	Type
Token	Authenticate with a Vault token.	Internal
TLS Certificate	Authenticate using SSL/TLS client certificates.	Internal
AppRole	Authenticate with HashiCorp Vault-defined roles.	Internal
JWT v3.13+	Authenticate with a JWT from an OIDC provider.	External
Kubernetes	Authenticate using a Kubernetes Service Account token. This method is suitable when Kong Gateway Enterprise runs inside a Kubernetes cluster.	External
AWS v3.14+	Authenticate using AWS IAM credentials, including the AWS EC2/IAM auth method supported by HashiCorp Vault.	External
Azure v3.14+	Authenticate using Azure Microsoft Entra credentials.	External
GCP v3.14+	Authenticate using GCP IAM credentials.	External

Create a HashiCorp Vault

The following example creates an hcv Vault entity:

kong.yaml

Copied!

_format_version: "3.0"
vaults:
  - name: hcv
    prefix: hashicorp-vault
    description: Storing secrets in HashiCorp Vault
    config:
      host: example-hcv-host
      token: example-hc-token
      kv: v2
      mount: secret
      port: 8200
      protocol: http

curl -i -X POST http://localhost:8001/vaults/ \
    --header "Accept: application/json" \
    --header "Content-Type: application/json" \
    --data '
    {
      "name": "hcv",
      "prefix": "hashicorp-vault",
      "description": "Storing secrets in HashiCorp Vault",
      "config": {
        "host": "example-hcv-host",
        "token": "example-hc-token",
        "kv": "v2",
        "mount": "secret",
        "port": 8200,
        "protocol": "http"
      }
    }
    '

Copied!

To create a Vault entity, call the Konnect control plane config API’s /vaults endpoint.

curl -X POST https://{region}.api.konghq.com/v2/control-planes/{controlPlaneId}/core-entities/vaults/ \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $KONNECT_TOKEN" \
    --data '
    {
      "name": "hcv",
      "prefix": "hashicorp-vault",
      "description": "Storing secrets in HashiCorp Vault",
      "config": {
        "host": "example-hcv-host",
        "token": "example-hc-token",
        "kv": "v2",
        "mount": "secret",
        "port": 8200,
        "protocol": "http"
      }
    }
    '

Copied!

echo "
apiVersion: configuration.konghq.com/v1alpha1
kind: KongVault
metadata:
  name: hcv-vault
  namespace: kong
  annotations:
    kubernetes.io/ingress.class: kong
spec:
  backend: hcv
  prefix: hashicorp-vault
  description: Storing secrets in HashiCorp Vault
  config:
    host: example-hcv-host
    token: example-hc-token
    kv: v2
    mount: secret
    port: 8200
    protocol: http
" | kubectl apply -f -

Copied!

resource "konnect_gateway_vault" "my_vault" {
  prefix = "hashicorp-vault"
  description = "Storing secrets in HashiCorp Vault"
  config = {
    host = "example-hcv-host"
    token = "example-hc-token"
    kv = "v2"
    mount = "secret"
    port = 8200
    protocol = "http"
  }

  control_plane_id = konnect_gateway_control_plane.my_konnect_cp.id
}

Copied!

Vault configuration options

The following table lists the available configuration parameters for a HashiCorp Vault:

Field name	Parameter format	Description
Protocol	Vault entity: `vaults.config.protocol` kong.conf parameter: `vault_hcv_protocol` Environment variable: `KONG_VAULT_HCV_PROTOCOL`	The protocol to connect with. Accepts one of `http` or `https`.
Host	Vault entity: `vaults.config.host` kong.conf parameter: `vault_hcv_host` Environment variable: `KONG_VAULT_HCV_HOST`	The hostname of your HashiCorp vault.
Port	Vault entity: `vaults.config.port` kong.conf parameter: `vault_hcv_port` Environment variable: `KONG_VAULT_HCV_PORT`	The port number of your HashiCorp vault.
Mount	Vault entity: `vaults.config.mount` kong.conf parameter: `vault_hcv_mount` Environment variable: `KONG_VAULT_HCV_MOUNT`	The mount point.
Kv	Vault entity: `vaults.config.kv` kong.conf parameter: `vault_hcv_kv` Environment variable: `KONG_VAULT_HCV_KV`	The secrets engine version. Accepts `v1` or `v2`.
Token	Vault entity: `vaults.config.token` kong.conf parameter: `vault_hcv_token` Environment variable: `KONG_VAULT_HCV_TOKEN`	A token string.
TTL	Vault entity: `vaults.config.ttl` kong.conf parameter: `vault_hcv_ttl` Environment variable: `KONG_VAULT_HCV_TTL`	Time-to-live (in seconds) for a cached secret. A value of 0 (default) disables rotation. For non-zero values, use at least 60 seconds.
Negative TTL	Vault entity: `vaults.config.neg_ttl` kong.conf parameter: `vault_hcv_neg_ttl` Environment variable: `KONG_VAULT_HCV_NEG_TTL`	Time-to-live (in seconds) for caching failed secret lookups. A value of 0 (default) disables negative caching. Kong retries after `neg_ttl` expires.
Resurrect TTL	Vault entity: `vaults.config.resurrect_ttl` kong.conf parameter: `vault_hcv_resurrect_ttl` Environment variable: `KONG_VAULT_HCV_RESURRECT_TTL`	Time (in seconds) that secrets remain in use after expiration (`config.ttl` is over). Useful if the vault is unreachable or a secret is deleted. Kong continues retrying for `resurrect_ttl` seconds, then stops. Default is 1e8 seconds (~3 years).
Namespace v3.1+	Vault entity: `vaults.config.namespace` kong.conf parameter: `vault_hcv_namespace` Environment variable: `KONG_VAULT_HCV_NAMESPACE`	Namespace for the Vault. Vault Enterprise requires a namespace to connect successfully.
Authentication Method v3.1+	Vault entity: `vaults.config.auth_method` kong.conf parameter: `vault_hcv_auth_method` Environment variable: `KONG_VAULT_HCV_AUTH_METHOD`	Defines the authentication mechanism for connecting to the HashiCorp Vault service. Accepts `token`, `kubernetes`, `approle`, `cert`, `jwt`, `gcp_iam`, `gcp_gce`, `azure`, `aws_ec2`, or `aws_iam`. For `jwt`, the IdP SSL certificate must be present in the Lua SSL trusted certificate when using HTTPS.
Kubernetes Role v3.1+	Vault entity: `vaults.config.kube_role` kong.conf parameter: `vault_hcv_kube_role` Environment variable: `KONG_VAULT_HCV_KUBE_ROLE`	Role assigned to the Kubernetes service account. Only used when `keyring_vault_auth_method` is set to `kubernetes`.
Kubernetes API Token File v3.1+	Vault entity: `vaults.config.kube_api_token_file` kong.conf parameter: `vault_hcv_kube_api_token_file` Environment variable: `KONG_VAULT_HCV_KUBE_API_TOKEN_FILE`	Path to the Kubernetes service account token file. Defaults to `/run/secrets/kubernetes.io/serviceaccount/token` if unspecified.
Kubernetes Auth Path v3.4+	Vault entity: `vaults.config.kube_auth_path` kong.conf parameter: `vault_hcv_kube_auth_path` Environment variable: `KONG_VAULT_HCV_KUBE_AUTH_PATH`	Path for enabling the Kubernetes auth method. Defaults to `kubernetes`. Single leading/trailing slashes are trimmed.
App Role Auth Path v3.4+	Vault entity: `vaults.config.approle_auth_path` kong.conf parameter: `vault_hcv_approle_auth_path` Environment variable: `KONG_VAULT_HCV_APPROLE_AUTH_PATH`	Path for enabling the AppRole auth method. Defaults to `AppRole`. Single leading/trailing slashes are trimmed.
App Role Role ID v3.4+	Vault entity: `vaults.config.approle_role_id` kong.conf parameter: `vault_hcv_approle_role_id` Environment variable: `KONG_VAULT_HCV_APPROLE_ROLE_ID`	Specifies the AppRole role ID in HashiCorp Vault.
App Role Secret ID v3.4+	Vault entity: `vaults.config.approle_secret_id` kong.conf parameter: `vault_hcv_approle_secret_id` Environment variable: `KONG_VAULT_HCV_APPROLE_SECRET_ID`	Defines the AppRole’s secret ID in HashiCorp Vault.
App Role Secret ID File v3.4+	Vault entity: `vaults.config.approle_secret_id_file` kong.conf parameter: `vault_hcv_approle_secret_id_file` Environment variable: `KONG_VAULT_HCV_APPROLE_SECRET_ID_FILE`	Path to a file containing the AppRole secret ID.
App Role Response Wrapping v3.4+	Vault entity: `vaults.config.approle_response_wrapping` kong.conf parameter: `vault_hcv_approle_response_wrapping` Environment variable: `KONG_VAULT_HCV_APPROLE_RESPONSE_WRAPPING`	Whether the secret ID is a response-wrapping token. Defaults to `false`. When `true`, Kong unwraps the token to get the actual secret ID. Note: tokens can only be unwrapped once; distribute them individually to Kong nodes.
Cert Key v3.11+	Vault entity: `vaults.config.cert_auth_cert_key` kong.conf parameter: `vault_hcv_cert_auth_cert_key` Environment variable: `KONG_VAULT_HCV_CERT_AUTH_CERT_KEY`	The key file for the client certificate.
Cert v3.11+	Vault entity: `vaults.config.cert_auth_cert` kong.conf parameter: `vault_hcv_cert_auth_cert` Environment variable: `KONG_VAULT_HCV_CERT_AUTH_CERT`	The client certificate file.
Role Name v3.11+	Vault entity: `vaults.config.cert_auth_role_name` kong.conf parameter: `vault_hcv_cert_auth_role_name` Environment variable: `KONG_VAULT_HCV_CERT_AUTH_ROLE_NAME`	The trusted certificate role name.
OAuth2 Role Name v3.13+	Vault entity: `vaults.config.oauth2_role_name` kong.conf parameter: `vault_hcv_oauth2_role_name` Environment variable: `KONG_VAULT_HCV_OAUTH2_ROLE_NAME`	The configured role name in HashiCorp Vault for OAuth2 auth. When creating the role in HashiCorp Vault, make sure that the `role_type` is `jwt` and the `token_policies` have permissions to read the secrets.
OAuth2 Token Endpoint v3.13+	Vault entity: `vaults.config.oauth2_token_endpoint` kong.conf parameter: `vault_hcv_oauth2_token_endpoint` Environment variable: `KONG_VAULT_HCV_OAUTH2_TOKEN_ENDPOINT`	The OAuth2 token endpoint for Hashicorp Vault’s OAuth2 auth method.
OAuth2 Client ID v3.13+	Vault entity: `vaults.config.oauth2_client_id` kong.conf parameter: `vault_hcv_oauth2_client_id` Environment variable: `KONG_VAULT_HCV_OAUTH2_CLIENT_ID`	The OAuth2 client ID.
OAuth2 Client Secret v3.13+	Vault entity: `vaults.config.oauth2_client_secret` kong.conf parameter: `vault_hcv_oauth2_client_secret` Environment variable: `KONG_VAULT_HCV_OAUTH2_CLIENT_SECRET`	The OAuth2 client secret.
OAuth2 Audiences v3.13+	Vault entity: `vaults.config.oauth2_audiences` kong.conf parameter: `vault_hcv_oauth2_audiences` Environment variable: `KONG_VAULT_HCV_OAUTH2_AUDIENCES`	Comma-separated list of OAuth2 audiences.
GCP Auth Role v3.14+	Vault entity: `vaults.config.gcp_auth_role` kong.conf parameter: `vault_hcv_gcp_auth_role` Environment variable: `KONG_VAULT_HCV_GCP_AUTH_ROLE`	The configured role name in HashiCorp Vault for GCP auth. Required when `auth_method` is `gcp_iam` or `gcp_gce`.
GCP Login Path v3.14+	Vault entity: `vaults.config.gcp_login_path` kong.conf parameter: `vault_hcv_gcp_login_path` Environment variable: `KONG_VAULT_HCV_GCP_LOGIN_PATH`	The login path for GCP auth in HashiCorp Vault. Used with both `gcp_iam` and `gcp_gce` auth methods. Defaults to `/v1/auth/gcp/login`.
GCP Service Account v3.14+	Vault entity: `vaults.config.gcp_service_account` kong.conf parameter: `vault_hcv_gcp_service_account` Environment variable: `KONG_VAULT_HCV_GCP_SERVICE_ACCOUNT`	The GCP service account email or identifier used for authentication. Required when `auth_method` is `gcp_iam`.
GCP JWT Expiration v3.14+	Vault entity: `vaults.config.gcp_jwt_exp` kong.conf parameter: `vault_hcv_gcp_jwt_exp` Environment variable: `KONG_VAULT_HCV_GCP_JWT_EXP`	The expiration time for the GCP JWT token in seconds. Must be between 0 and 900. Required when `auth_method` is `gcp_iam`.
Azure Auth Role v3.14+	Vault entity: `vaults.config.azure_auth_role` kong.conf parameter: `vault_hcv_azure_auth_role` Environment variable: `KONG_VAULT_HCV_AZURE_AUTH_ROLE`	The configured role name in HashiCorp Vault for Azure auth. When creating the role in HashiCorp Vault, make sure that the `role_type` is `azure` and the `token_policies` have permissions to read the secrets. Required when `auth_method` is `azure`.
Azure Login Path v3.14+	Vault entity: `vaults.config.azure_login_path` kong.conf parameter: `vault_hcv_azure_login_path` Environment variable: `KONG_VAULT_HCV_AZURE_LOGIN_PATH`	The login path for Azure auth in HashiCorp Vault. Defaults to `/v1/auth/azure/login`.
AWS Auth Role v3.14+	Vault entity: `vaults.config.aws_auth_role` kong.conf parameter: `vault_hcv_aws_auth_role` Environment variable: `KONG_VAULT_HCV_AWS_AUTH_ROLE`	The configured role name in HashiCorp Vault for AWS auth. When creating the role in HashiCorp Vault, make sure that the `role_type` is `aws` and the `token_policies` have permissions to read the secrets. Required when `auth_method` is `aws_ec2` or `aws_iam`.
AWS Login Path v3.14+	Vault entity: `vaults.config.aws_login_path` kong.conf parameter: `vault_hcv_aws_login_path` Environment variable: `KONG_VAULT_HCV_AWS_LOGIN_PATH`	The login path for AWS auth in HashiCorp Vault. Used with both `aws_ec2` and `aws_iam` auth methods. Defaults to `/v1/auth/aws/login`.
AWS Auth Region v3.14+	Vault entity: `vaults.config.aws_auth_region` kong.conf parameter: `vault_hcv_aws_auth_region` Environment variable: `KONG_VAULT_HCV_AWS_AUTH_REGION`	The AWS region for the AWS auth method. Required when `auth_method` is `aws_iam`.
AWS Auth Nonce v3.14+	Vault entity: `vaults.config.aws_auth_nonce` kong.conf parameter: `vault_hcv_aws_auth_nonce` Environment variable: `KONG_VAULT_HCV_AWS_AUTH_NONCE`	The nonce used for the AWS EC2 auth method. Required when `auth_method` is `aws_ec2`.
AWS Access Key ID v3.14+	Vault entity: `vaults.config.aws_access_key_id` kong.conf parameter: `vault_hcv_aws_access_key_id` Environment variable: `KONG_VAULT_HCV_AWS_ACCESS_KEY_ID`	The AWS access key ID for AWS IAM authentication. If not provided, the default credentials provider chain is used. Must be set together with `aws_secret_access_key`.
AWS Secret Access Key v3.14+	Vault entity: `vaults.config.aws_secret_access_key` kong.conf parameter: `vault_hcv_aws_secret_access_key` Environment variable: `KONG_VAULT_HCV_AWS_SECRET_ACCESS_KEY`	The AWS secret access key for AWS IAM authentication. If not provided, the default credentials provider chain is used. Must be set together with `aws_access_key_id`.
AWS STS Endpoint URL v3.14+	Vault entity: `vaults.config.aws_sts_endpoint_url` kong.conf parameter: `vault_hcv_aws_sts_endpoint_url` Environment variable: `KONG_VAULT_HCV_AWS_STS_ENDPOINT_URL`	The AWS STS endpoint URL used by Kong Gateway when signing the `GetCallerIdentity` request for AWS IAM authentication. If not provided, defaults to the standard STS endpoint for the specified region. This setting only affects the STS endpoint that Kong Gateway itself contacts — it does not influence which STS endpoint HashiCorp Vault uses on its side.
AWS Assume Role ARN v3.14+	Vault entity: `vaults.config.aws_assume_role_arn` kong.conf parameter: `vault_hcv_aws_assume_role_arn` Environment variable: `KONG_VAULT_HCV_AWS_ASSUME_ROLE_ARN`	The ARN of the AWS IAM role to assume for authentication. Must be set together with `aws_role_session_name`.
AWS Role Session Name v3.14+	Vault entity: `vaults.config.aws_role_session_name` kong.conf parameter: `vault_hcv_aws_role_session_name` Environment variable: `KONG_VAULT_HCV_AWS_ROLE_SESSION_NAME`	The session name to use when assuming an AWS IAM role. Defaults to `kong`. Must be set together with `aws_assume_role_arn`.

HashiCorp Vault

HashiCorp Vault cloud authentication

Supported authentication methods

Create a HashiCorp Vault

Vault configuration options

Tutorials

Help us make these docs great!

Still need help?