Home / Kong Gateway / Kong Gateway entities
Edit
Report

Vaults

Uses: Kong Gateway Admin API deck KIC Konnect API Terraform
Related Documentation
Gateway Documentation
OpenAPI Specifications
Gateway Admin - EE
Konnect Control Planes Config
Tags
#secrets-management
Related Resources
Secrets Management
Workspaces
RBAC
Reserved entity names
Managing sensitive data with decK
Konnect Control Plane resource limits
Cloud provider integration support for Kong Gateway Enterprise

What is a Vault?

Vaults allow you to securely store and then reference secrets from within other entities. This ensures that secrets aren’t visible in plaintext throughout the platform, in places such as kong.conf, declarative configuration files, logs, or the UI.

For example, you could store a certificate and a key in a Vault, then reference them from a Certificate entity. This way, the certificate and key are not stored in the entity directly and are more secure.

How do I add secrets to a Vault?

You can add secrets to Vaults in one of the following ways:

  • Environment variables
  • Konnect Config Store
  • Supported third-party backend vault

What can be stored as a secret?

You can store and reference the following as secrets in a Vault:

  • All values1 set in kong.conf are referenceable. For example:
    • Data store usernames and passwords, used with PostgreSQL and Redis
    • Private X.509 certificates
  • Certificates and keys stored in the Certificate Kong Gateway entity
  • Kong Gateway license2
  • Referenceable plugin fields, such as third-party API keys (see table below for all values)

Konnect Config Store limitations:

  • 1: You can’t reference secrets stored in a Konnect Config Store Vault in kong.conf because Konnect resolves the secret after Kong Gateway connects to the Control Plane. For this same reason, you can’t use Konnect Config Store secrets directly in Lua code via the Kong PDK, for example.
  • 2: In Konnect, the Kong Gateway license is managed and stored by Konnect, and doesn’t need to be stored manually in any Vault.

Referenceable plugin fields

The following plugin fields can be stored and referenced as secrets:

Plugin Referenceable Plugin Fields
Access Control Enforcement
(ace)
  • config.rate_limiting.redis.cloud_authentication.auth_provider
  • config.rate_limiting.redis.cloud_authentication.aws_access_key_id
  • config.rate_limiting.redis.cloud_authentication.aws_assume_role_arn
  • config.rate_limiting.redis.cloud_authentication.aws_cache_name
  • config.rate_limiting.redis.cloud_authentication.aws_region
  • config.rate_limiting.redis.cloud_authentication.aws_role_session_name
  • config.rate_limiting.redis.cloud_authentication.aws_secret_access_key
  • config.rate_limiting.redis.cloud_authentication.azure_client_id
  • config.rate_limiting.redis.cloud_authentication.azure_client_secret
  • config.rate_limiting.redis.cloud_authentication.azure_tenant_id
  • config.rate_limiting.redis.cloud_authentication.gcp_service_account_json
  • config.rate_limiting.redis.host
  • config.rate_limiting.redis.password
  • config.rate_limiting.redis.port
  • config.rate_limiting.redis.sentinel_password
  • config.rate_limiting.redis.sentinel_username
  • config.rate_limiting.redis.server_name
  • config.rate_limiting.redis.username
ACME
(acme)
  • config.account_email
  • config.eab_hmac_key
  • config.eab_kid
  • config.storage_config.consul.token
  • config.storage_config.redis.cloud_authentication.auth_provider
  • config.storage_config.redis.cloud_authentication.aws_access_key_id
  • config.storage_config.redis.cloud_authentication.aws_assume_role_arn
  • config.storage_config.redis.cloud_authentication.aws_cache_name
  • config.storage_config.redis.cloud_authentication.aws_region
  • config.storage_config.redis.cloud_authentication.aws_role_session_name
  • config.storage_config.redis.cloud_authentication.aws_secret_access_key
  • config.storage_config.redis.cloud_authentication.azure_client_id
  • config.storage_config.redis.cloud_authentication.azure_client_secret
  • config.storage_config.redis.cloud_authentication.azure_tenant_id
  • config.storage_config.redis.cloud_authentication.gcp_service_account_json
  • config.storage_config.redis.host
  • config.storage_config.redis.password
  • config.storage_config.redis.port
  • config.storage_config.redis.server_name
  • config.storage_config.redis.username
  • config.storage_config.vault.token
AI AWS Guardrails
(ai-aws-guardrails)
  • config.aws_access_key_id
  • config.aws_secret_access_key
AI Azure Content Safety
(ai-azure-content-safety)
  • config.content_safety_key
  • config.content_safety_url
AI Custom Guardrail
(ai-custom-guardrail)
  • config.params
  • config.params.additionalProperties
  • config.request.auth.name
  • config.request.auth.value
  • config.request.body
  • config.request.body.additionalProperties
  • config.request.headers
  • config.request.headers.additionalProperties
  • config.request.queries
  • config.request.queries.additionalProperties
AI GCP Model Armor
(ai-gcp-model-armor)
  • config.gcp_metadata_url
  • config.gcp_oauth_token_url
  • config.gcp_service_account_json
AI Lakera Guard
(ai-lakera-guard)
  • config.api_key
  • config.lakera_service_url
  • config.project_id
AI LLM as Judge
(ai-llm-as-judge)
  • config.llm.auth.aws_access_key_id
  • config.llm.auth.aws_secret_access_key
  • config.llm.auth.azure_client_id
  • config.llm.auth.azure_client_secret
  • config.llm.auth.azure_tenant_id
  • config.llm.auth.gcp_metadata_url
  • config.llm.auth.gcp_oauth_token_url
  • config.llm.auth.gcp_service_account_json
  • config.llm.auth.header_name
  • config.llm.auth.header_value
  • config.llm.auth.param_name
  • config.llm.auth.param_value
AI MCP OAuth2
(ai-mcp-oauth2)
  • config.client_id
  • config.client_jwk
  • config.client_secret
  • config.token_exchange.client_id
  • config.token_exchange.client_secret
AI MCP Proxy
(ai-mcp-proxy)
  • config.server.session.client.secrets
  • config.server.session.redis.cloud_authentication.auth_provider
  • config.server.session.redis.cloud_authentication.aws_access_key_id
  • config.server.session.redis.cloud_authentication.aws_assume_role_arn
  • config.server.session.redis.cloud_authentication.aws_cache_name
  • config.server.session.redis.cloud_authentication.aws_region
  • config.server.session.redis.cloud_authentication.aws_role_session_name
  • config.server.session.redis.cloud_authentication.aws_secret_access_key
  • config.server.session.redis.cloud_authentication.azure_client_id
  • config.server.session.redis.cloud_authentication.azure_client_secret
  • config.server.session.redis.cloud_authentication.azure_tenant_id
  • config.server.session.redis.cloud_authentication.gcp_service_account_json
  • config.server.session.redis.host
  • config.server.session.redis.password
  • config.server.session.redis.port
  • config.server.session.redis.sentinel_password
  • config.server.session.redis.sentinel_username
  • config.server.session.redis.server_name
  • config.server.session.redis.username
AI Proxy
(ai-proxy)
  • config.auth.aws_access_key_id
  • config.auth.aws_secret_access_key
  • config.auth.azure_client_id
  • config.auth.azure_client_secret
  • config.auth.azure_tenant_id
  • config.auth.gcp_metadata_url
  • config.auth.gcp_oauth_token_url
  • config.auth.gcp_service_account_json
  • config.auth.header_name
  • config.auth.header_value
  • config.auth.param_name
  • config.auth.param_value
AI Proxy Advanced
(ai-proxy-advanced)
  • config.embeddings.auth.aws_access_key_id
  • config.embeddings.auth.aws_secret_access_key
  • config.embeddings.auth.azure_client_id
  • config.embeddings.auth.azure_client_secret
  • config.embeddings.auth.azure_tenant_id
  • config.embeddings.auth.gcp_metadata_url
  • config.embeddings.auth.gcp_oauth_token_url
  • config.embeddings.auth.gcp_service_account_json
  • config.embeddings.auth.header_name
  • config.embeddings.auth.header_value
  • config.embeddings.auth.param_name
  • config.embeddings.auth.param_value
  • config.targets.auth.aws_access_key_id
  • config.targets.auth.aws_secret_access_key
  • config.targets.auth.azure_client_id
  • config.targets.auth.azure_client_secret
  • config.targets.auth.azure_tenant_id
  • config.targets.auth.gcp_metadata_url
  • config.targets.auth.gcp_oauth_token_url
  • config.targets.auth.gcp_service_account_json
  • config.targets.auth.header_name
  • config.targets.auth.header_value
  • config.targets.auth.param_name
  • config.targets.auth.param_value
  • config.vectordb.pgvector.password
  • config.vectordb.pgvector.user
  • config.vectordb.redis.cloud_authentication.auth_provider
  • config.vectordb.redis.cloud_authentication.aws_access_key_id
  • config.vectordb.redis.cloud_authentication.aws_assume_role_arn
  • config.vectordb.redis.cloud_authentication.aws_cache_name
  • config.vectordb.redis.cloud_authentication.aws_region
  • config.vectordb.redis.cloud_authentication.aws_role_session_name
  • config.vectordb.redis.cloud_authentication.aws_secret_access_key
  • config.vectordb.redis.cloud_authentication.azure_client_id
  • config.vectordb.redis.cloud_authentication.azure_client_secret
  • config.vectordb.redis.cloud_authentication.azure_tenant_id
  • config.vectordb.redis.cloud_authentication.gcp_service_account_json
  • config.vectordb.redis.host
  • config.vectordb.redis.password
  • config.vectordb.redis.port
  • config.vectordb.redis.sentinel_password
  • config.vectordb.redis.sentinel_username
  • config.vectordb.redis.server_name
  • config.vectordb.redis.username
AI RAG Injector
(ai-rag-injector)
  • config.embeddings.auth.aws_access_key_id
  • config.embeddings.auth.aws_secret_access_key
  • config.embeddings.auth.azure_client_id
  • config.embeddings.auth.azure_client_secret
  • config.embeddings.auth.azure_tenant_id
  • config.embeddings.auth.gcp_metadata_url
  • config.embeddings.auth.gcp_oauth_token_url
  • config.embeddings.auth.gcp_service_account_json
  • config.embeddings.auth.header_name
  • config.embeddings.auth.header_value
  • config.embeddings.auth.param_name
  • config.embeddings.auth.param_value
  • config.vectordb.pgvector.password
  • config.vectordb.pgvector.user
  • config.vectordb.redis.cloud_authentication.auth_provider
  • config.vectordb.redis.cloud_authentication.aws_access_key_id
  • config.vectordb.redis.cloud_authentication.aws_assume_role_arn
  • config.vectordb.redis.cloud_authentication.aws_cache_name
  • config.vectordb.redis.cloud_authentication.aws_region
  • config.vectordb.redis.cloud_authentication.aws_role_session_name
  • config.vectordb.redis.cloud_authentication.aws_secret_access_key
  • config.vectordb.redis.cloud_authentication.azure_client_id
  • config.vectordb.redis.cloud_authentication.azure_client_secret
  • config.vectordb.redis.cloud_authentication.azure_tenant_id
  • config.vectordb.redis.cloud_authentication.gcp_service_account_json
  • config.vectordb.redis.host
  • config.vectordb.redis.password
  • config.vectordb.redis.port
  • config.vectordb.redis.sentinel_password
  • config.vectordb.redis.sentinel_username
  • config.vectordb.redis.server_name
  • config.vectordb.redis.username
AI Rate Limiting Advanced
(ai-rate-limiting-advanced)
  • config.redis.cloud_authentication.auth_provider
  • config.redis.cloud_authentication.aws_access_key_id
  • config.redis.cloud_authentication.aws_assume_role_arn
  • config.redis.cloud_authentication.aws_cache_name
  • config.redis.cloud_authentication.aws_region
  • config.redis.cloud_authentication.aws_role_session_name
  • config.redis.cloud_authentication.aws_secret_access_key
  • config.redis.cloud_authentication.azure_client_id
  • config.redis.cloud_authentication.azure_client_secret
  • config.redis.cloud_authentication.azure_tenant_id
  • config.redis.cloud_authentication.gcp_service_account_json
  • config.redis.host
  • config.redis.password
  • config.redis.port
  • config.redis.sentinel_password
  • config.redis.sentinel_username
  • config.redis.server_name
  • config.redis.username
AI Request Transformer
(ai-request-transformer)
  • config.llm.auth.aws_access_key_id
  • config.llm.auth.aws_secret_access_key
  • config.llm.auth.azure_client_id
  • config.llm.auth.azure_client_secret
  • config.llm.auth.azure_tenant_id
  • config.llm.auth.gcp_metadata_url
  • config.llm.auth.gcp_oauth_token_url
  • config.llm.auth.gcp_service_account_json
  • config.llm.auth.header_name
  • config.llm.auth.header_value
  • config.llm.auth.param_name
  • config.llm.auth.param_value
AI Response Transformer
(ai-response-transformer)
  • config.llm.auth.aws_access_key_id
  • config.llm.auth.aws_secret_access_key
  • config.llm.auth.azure_client_id
  • config.llm.auth.azure_client_secret
  • config.llm.auth.azure_tenant_id
  • config.llm.auth.gcp_metadata_url
  • config.llm.auth.gcp_oauth_token_url
  • config.llm.auth.gcp_service_account_json
  • config.llm.auth.header_name
  • config.llm.auth.header_value
  • config.llm.auth.param_name
  • config.llm.auth.param_value
AI Semantic Cache
(ai-semantic-cache)
  • config.embeddings.auth.aws_access_key_id
  • config.embeddings.auth.aws_secret_access_key
  • config.embeddings.auth.azure_client_id
  • config.embeddings.auth.azure_client_secret
  • config.embeddings.auth.azure_tenant_id
  • config.embeddings.auth.gcp_metadata_url
  • config.embeddings.auth.gcp_oauth_token_url
  • config.embeddings.auth.gcp_service_account_json
  • config.embeddings.auth.header_name
  • config.embeddings.auth.header_value
  • config.embeddings.auth.param_name
  • config.embeddings.auth.param_value
  • config.vectordb.pgvector.password
  • config.vectordb.pgvector.user
  • config.vectordb.redis.cloud_authentication.auth_provider
  • config.vectordb.redis.cloud_authentication.aws_access_key_id
  • config.vectordb.redis.cloud_authentication.aws_assume_role_arn
  • config.vectordb.redis.cloud_authentication.aws_cache_name
  • config.vectordb.redis.cloud_authentication.aws_region
  • config.vectordb.redis.cloud_authentication.aws_role_session_name
  • config.vectordb.redis.cloud_authentication.aws_secret_access_key
  • config.vectordb.redis.cloud_authentication.azure_client_id
  • config.vectordb.redis.cloud_authentication.azure_client_secret
  • config.vectordb.redis.cloud_authentication.azure_tenant_id
  • config.vectordb.redis.cloud_authentication.gcp_service_account_json
  • config.vectordb.redis.host
  • config.vectordb.redis.password
  • config.vectordb.redis.port
  • config.vectordb.redis.sentinel_password
  • config.vectordb.redis.sentinel_username
  • config.vectordb.redis.server_name
  • config.vectordb.redis.username
AI Semantic Prompt Guard
(ai-semantic-prompt-guard)
  • config.embeddings.auth.aws_access_key_id
  • config.embeddings.auth.aws_secret_access_key
  • config.embeddings.auth.azure_client_id
  • config.embeddings.auth.azure_client_secret
  • config.embeddings.auth.azure_tenant_id
  • config.embeddings.auth.gcp_metadata_url
  • config.embeddings.auth.gcp_oauth_token_url
  • config.embeddings.auth.gcp_service_account_json
  • config.embeddings.auth.header_name
  • config.embeddings.auth.header_value
  • config.embeddings.auth.param_name
  • config.embeddings.auth.param_value
  • config.vectordb.pgvector.password
  • config.vectordb.pgvector.user
  • config.vectordb.redis.cloud_authentication.auth_provider
  • config.vectordb.redis.cloud_authentication.aws_access_key_id
  • config.vectordb.redis.cloud_authentication.aws_assume_role_arn
  • config.vectordb.redis.cloud_authentication.aws_cache_name
  • config.vectordb.redis.cloud_authentication.aws_region
  • config.vectordb.redis.cloud_authentication.aws_role_session_name
  • config.vectordb.redis.cloud_authentication.aws_secret_access_key
  • config.vectordb.redis.cloud_authentication.azure_client_id
  • config.vectordb.redis.cloud_authentication.azure_client_secret
  • config.vectordb.redis.cloud_authentication.azure_tenant_id
  • config.vectordb.redis.cloud_authentication.gcp_service_account_json
  • config.vectordb.redis.host
  • config.vectordb.redis.password
  • config.vectordb.redis.port
  • config.vectordb.redis.sentinel_password
  • config.vectordb.redis.sentinel_username
  • config.vectordb.redis.server_name
  • config.vectordb.redis.username
AI Semantic Response Guard
(ai-semantic-response-guard)
  • config.embeddings.auth.aws_access_key_id
  • config.embeddings.auth.aws_secret_access_key
  • config.embeddings.auth.azure_client_id
  • config.embeddings.auth.azure_client_secret
  • config.embeddings.auth.azure_tenant_id
  • config.embeddings.auth.gcp_metadata_url
  • config.embeddings.auth.gcp_oauth_token_url
  • config.embeddings.auth.gcp_service_account_json
  • config.embeddings.auth.header_name
  • config.embeddings.auth.header_value
  • config.embeddings.auth.param_name
  • config.embeddings.auth.param_value
  • config.vectordb.pgvector.password
  • config.vectordb.pgvector.user
  • config.vectordb.redis.cloud_authentication.auth_provider
  • config.vectordb.redis.cloud_authentication.aws_access_key_id
  • config.vectordb.redis.cloud_authentication.aws_assume_role_arn
  • config.vectordb.redis.cloud_authentication.aws_cache_name
  • config.vectordb.redis.cloud_authentication.aws_region
  • config.vectordb.redis.cloud_authentication.aws_role_session_name
  • config.vectordb.redis.cloud_authentication.aws_secret_access_key
  • config.vectordb.redis.cloud_authentication.azure_client_id
  • config.vectordb.redis.cloud_authentication.azure_client_secret
  • config.vectordb.redis.cloud_authentication.azure_tenant_id
  • config.vectordb.redis.cloud_authentication.gcp_service_account_json
  • config.vectordb.redis.host
  • config.vectordb.redis.password
  • config.vectordb.redis.port
  • config.vectordb.redis.sentinel_password
  • config.vectordb.redis.sentinel_username
  • config.vectordb.redis.server_name
  • config.vectordb.redis.username
AWS Lambda
(aws-lambda)
  • config.aws_assume_role_arn
  • config.aws_key
  • config.aws_secret
Azure Functions
(azure-functions)
  • config.apikey
  • config.clientid
Basic Auth
(basic-auth)
  • config.brute_force_protection.redis.cloud_authentication.auth_provider
  • config.brute_force_protection.redis.cloud_authentication.aws_access_key_id
  • config.brute_force_protection.redis.cloud_authentication.aws_assume_role_arn
  • config.brute_force_protection.redis.cloud_authentication.aws_cache_name
  • config.brute_force_protection.redis.cloud_authentication.aws_region
  • config.brute_force_protection.redis.cloud_authentication.aws_role_session_name
  • config.brute_force_protection.redis.cloud_authentication.aws_secret_access_key
  • config.brute_force_protection.redis.cloud_authentication.azure_client_id
  • config.brute_force_protection.redis.cloud_authentication.azure_client_secret
  • config.brute_force_protection.redis.cloud_authentication.azure_tenant_id
  • config.brute_force_protection.redis.cloud_authentication.gcp_service_account_json
  • config.brute_force_protection.redis.host
  • config.brute_force_protection.redis.password
  • config.brute_force_protection.redis.port
  • config.brute_force_protection.redis.server_name
  • config.brute_force_protection.redis.username
Confluent
(confluent)
  • config.cluster_api_key
  • config.cluster_api_secret
  • config.confluent_cloud_api_key
  • config.confluent_cloud_api_secret
  • config.schema_registry.confluent.authentication.basic.password
  • config.schema_registry.confluent.authentication.basic.username
  • config.schema_registry.confluent.authentication.oauth2.client_id
  • config.schema_registry.confluent.authentication.oauth2.client_secret
  • config.schema_registry.confluent.authentication.oauth2.password
  • config.schema_registry.confluent.authentication.oauth2.token_headers
  • config.schema_registry.confluent.authentication.oauth2.token_headers.additionalProperties
  • config.schema_registry.confluent.authentication.oauth2.token_post_args
  • config.schema_registry.confluent.authentication.oauth2.token_post_args.additionalProperties
  • config.schema_registry.confluent.authentication.oauth2.username
Confluent Consume
(confluent-consume)
  • config.cluster_api_key
  • config.cluster_api_secret
  • config.confluent_cloud_api_key
  • config.confluent_cloud_api_secret
  • config.schema_registry.confluent.authentication.basic.password
  • config.schema_registry.confluent.authentication.basic.username
  • config.schema_registry.confluent.authentication.oauth2.client_id
  • config.schema_registry.confluent.authentication.oauth2.client_secret
  • config.schema_registry.confluent.authentication.oauth2.password
  • config.schema_registry.confluent.authentication.oauth2.token_headers
  • config.schema_registry.confluent.authentication.oauth2.token_headers.additionalProperties
  • config.schema_registry.confluent.authentication.oauth2.token_post_args
  • config.schema_registry.confluent.authentication.oauth2.token_post_args.additionalProperties
  • config.schema_registry.confluent.authentication.oauth2.username
  • config.topics.schema_registry.confluent.authentication.basic.password
  • config.topics.schema_registry.confluent.authentication.basic.username
  • config.topics.schema_registry.confluent.authentication.oauth2.client_id
  • config.topics.schema_registry.confluent.authentication.oauth2.client_secret
  • config.topics.schema_registry.confluent.authentication.oauth2.password
  • config.topics.schema_registry.confluent.authentication.oauth2.token_headers
  • config.topics.schema_registry.confluent.authentication.oauth2.token_headers.additionalProperties
  • config.topics.schema_registry.confluent.authentication.oauth2.token_post_args
  • config.topics.schema_registry.confluent.authentication.oauth2.token_post_args.additionalProperties
  • config.topics.schema_registry.confluent.authentication.oauth2.username
Datadog
(datadog)
  • config.host
Datakit
(datakit)
  • config.resources.cache.redis.cloud_authentication.auth_provider
  • config.resources.cache.redis.cloud_authentication.aws_access_key_id
  • config.resources.cache.redis.cloud_authentication.aws_assume_role_arn
  • config.resources.cache.redis.cloud_authentication.aws_cache_name
  • config.resources.cache.redis.cloud_authentication.aws_region
  • config.resources.cache.redis.cloud_authentication.aws_role_session_name
  • config.resources.cache.redis.cloud_authentication.aws_secret_access_key
  • config.resources.cache.redis.cloud_authentication.azure_client_id
  • config.resources.cache.redis.cloud_authentication.azure_client_secret
  • config.resources.cache.redis.cloud_authentication.azure_tenant_id
  • config.resources.cache.redis.cloud_authentication.gcp_service_account_json
  • config.resources.cache.redis.host
  • config.resources.cache.redis.password
  • config.resources.cache.redis.port
  • config.resources.cache.redis.sentinel_password
  • config.resources.cache.redis.sentinel_username
  • config.resources.cache.redis.server_name
  • config.resources.cache.redis.username
  • config.resources.vault
  • config.resources.vault.additionalProperties
Forward Proxy Advanced
(forward-proxy)
  • config.auth_password
  • config.auth_username
GraphQL Proxy Caching Advanced
(graphql-proxy-cache-advanced)
  • config.redis.cloud_authentication.auth_provider
  • config.redis.cloud_authentication.aws_access_key_id
  • config.redis.cloud_authentication.aws_assume_role_arn
  • config.redis.cloud_authentication.aws_cache_name
  • config.redis.cloud_authentication.aws_region
  • config.redis.cloud_authentication.aws_role_session_name
  • config.redis.cloud_authentication.aws_secret_access_key
  • config.redis.cloud_authentication.azure_client_id
  • config.redis.cloud_authentication.azure_client_secret
  • config.redis.cloud_authentication.azure_tenant_id
  • config.redis.cloud_authentication.gcp_service_account_json
  • config.redis.host
  • config.redis.password
  • config.redis.port
  • config.redis.sentinel_password
  • config.redis.sentinel_username
  • config.redis.server_name
  • config.redis.username
GraphQL Rate Limiting Advanced
(graphql-rate-limiting-advanced)
  • config.redis.cloud_authentication.auth_provider
  • config.redis.cloud_authentication.aws_access_key_id
  • config.redis.cloud_authentication.aws_assume_role_arn
  • config.redis.cloud_authentication.aws_cache_name
  • config.redis.cloud_authentication.aws_region
  • config.redis.cloud_authentication.aws_role_session_name
  • config.redis.cloud_authentication.aws_secret_access_key
  • config.redis.cloud_authentication.azure_client_id
  • config.redis.cloud_authentication.azure_client_secret
  • config.redis.cloud_authentication.azure_tenant_id
  • config.redis.cloud_authentication.gcp_service_account_json
  • config.redis.host
  • config.redis.password
  • config.redis.port
  • config.redis.sentinel_password
  • config.redis.sentinel_username
  • config.redis.server_name
  • config.redis.username
HTTP Log
(http-log)
  • config.http_endpoint
JWT Signer
(jwt-signer)
  • config.access_token_jwks_uri_client_password
  • config.access_token_jwks_uri_client_username
  • config.access_token_keyset_client_password
  • config.access_token_keyset_client_username
  • config.channel_token_jwks_uri_client_password
  • config.channel_token_jwks_uri_client_username
  • config.channel_token_keyset_client_password
  • config.channel_token_keyset_client_username
Kafka Consume
(kafka-consume)
  • config.authentication.password
  • config.authentication.user
  • config.schema_registry.confluent.authentication.basic.password
  • config.schema_registry.confluent.authentication.basic.username
  • config.schema_registry.confluent.authentication.oauth2.client_id
  • config.schema_registry.confluent.authentication.oauth2.client_secret
  • config.schema_registry.confluent.authentication.oauth2.password
  • config.schema_registry.confluent.authentication.oauth2.token_headers
  • config.schema_registry.confluent.authentication.oauth2.token_headers.additionalProperties
  • config.schema_registry.confluent.authentication.oauth2.token_post_args
  • config.schema_registry.confluent.authentication.oauth2.token_post_args.additionalProperties
  • config.schema_registry.confluent.authentication.oauth2.username
  • config.topics.schema_registry.confluent.authentication.basic.password
  • config.topics.schema_registry.confluent.authentication.basic.username
  • config.topics.schema_registry.confluent.authentication.oauth2.client_id
  • config.topics.schema_registry.confluent.authentication.oauth2.client_secret
  • config.topics.schema_registry.confluent.authentication.oauth2.password
  • config.topics.schema_registry.confluent.authentication.oauth2.token_headers
  • config.topics.schema_registry.confluent.authentication.oauth2.token_headers.additionalProperties
  • config.topics.schema_registry.confluent.authentication.oauth2.token_post_args
  • config.topics.schema_registry.confluent.authentication.oauth2.token_post_args.additionalProperties
  • config.topics.schema_registry.confluent.authentication.oauth2.username
Kafka Log
(kafka-log)
  • config.authentication.password
  • config.authentication.user
  • config.schema_registry.confluent.authentication.basic.password
  • config.schema_registry.confluent.authentication.basic.username
  • config.schema_registry.confluent.authentication.oauth2.client_id
  • config.schema_registry.confluent.authentication.oauth2.client_secret
  • config.schema_registry.confluent.authentication.oauth2.password
  • config.schema_registry.confluent.authentication.oauth2.token_headers
  • config.schema_registry.confluent.authentication.oauth2.token_headers.additionalProperties
  • config.schema_registry.confluent.authentication.oauth2.token_post_args
  • config.schema_registry.confluent.authentication.oauth2.token_post_args.additionalProperties
  • config.schema_registry.confluent.authentication.oauth2.username
Kafka Upstream
(kafka-upstream)
  • config.authentication.password
  • config.authentication.user
  • config.schema_registry.confluent.authentication.basic.password
  • config.schema_registry.confluent.authentication.basic.username
  • config.schema_registry.confluent.authentication.oauth2.client_id
  • config.schema_registry.confluent.authentication.oauth2.client_secret
  • config.schema_registry.confluent.authentication.oauth2.password
  • config.schema_registry.confluent.authentication.oauth2.token_headers
  • config.schema_registry.confluent.authentication.oauth2.token_headers.additionalProperties
  • config.schema_registry.confluent.authentication.oauth2.token_post_args
  • config.schema_registry.confluent.authentication.oauth2.token_post_args.additionalProperties
  • config.schema_registry.confluent.authentication.oauth2.username
LDAP Authentication Advanced
(ldap-auth-advanced)
  • config.bind_dn
  • config.ldap_password
Loggly
(loggly)
  • config.key
Metering & Billing
(metering-and-billing)
  • config.api_token
  • config.ingest_endpoint
OAuth 2.0 Introspection
(oauth2-introspection)
  • config.authorization_value
OpenID Connect
(openid-connect)
  • config.client_id
  • config.client_jwk.d
  • config.client_jwk.dp
  • config.client_jwk.dq
  • config.client_jwk.k
  • config.client_jwk.oth
  • config.client_jwk.p
  • config.client_jwk.q
  • config.client_jwk.qi
  • config.client_jwk.r
  • config.client_jwk.t
  • config.client_secret
  • config.cluster_cache_redis.cloud_authentication.auth_provider
  • config.cluster_cache_redis.cloud_authentication.aws_access_key_id
  • config.cluster_cache_redis.cloud_authentication.aws_assume_role_arn
  • config.cluster_cache_redis.cloud_authentication.aws_cache_name
  • config.cluster_cache_redis.cloud_authentication.aws_region
  • config.cluster_cache_redis.cloud_authentication.aws_role_session_name
  • config.cluster_cache_redis.cloud_authentication.aws_secret_access_key
  • config.cluster_cache_redis.cloud_authentication.azure_client_id
  • config.cluster_cache_redis.cloud_authentication.azure_client_secret
  • config.cluster_cache_redis.cloud_authentication.azure_tenant_id
  • config.cluster_cache_redis.cloud_authentication.gcp_service_account_json
  • config.cluster_cache_redis.host
  • config.cluster_cache_redis.password
  • config.cluster_cache_redis.port
  • config.cluster_cache_redis.sentinel_password
  • config.cluster_cache_redis.sentinel_username
  • config.cluster_cache_redis.server_name
  • config.cluster_cache_redis.username
  • config.extra_jwks_uris
  • config.http_proxy_authorization
  • config.https_proxy_authorization
  • config.introspection_endpoint
  • config.introspection_headers_values
  • config.issuer
  • config.issuers_allowed
  • config.login_redirect_uri
  • config.logout_redirect_uri
  • config.redis.cloud_authentication.auth_provider
  • config.redis.cloud_authentication.aws_access_key_id
  • config.redis.cloud_authentication.aws_assume_role_arn
  • config.redis.cloud_authentication.aws_cache_name
  • config.redis.cloud_authentication.aws_region
  • config.redis.cloud_authentication.aws_role_session_name
  • config.redis.cloud_authentication.aws_secret_access_key
  • config.redis.cloud_authentication.azure_client_id
  • config.redis.cloud_authentication.azure_client_secret
  • config.redis.cloud_authentication.azure_tenant_id
  • config.redis.cloud_authentication.gcp_service_account_json
  • config.redis.host
  • config.redis.password
  • config.redis.port
  • config.redis.sentinel_password
  • config.redis.sentinel_username
  • config.redis.server_name
  • config.redis.username
  • config.scopes
  • config.session_secret
OpenTelemetry
(opentelemetry)
  • config.access_logs.endpoint
  • config.logs_endpoint
  • config.metrics.endpoint
  • config.traces_endpoint
Proxy Caching Advanced
(proxy-cache-advanced)
  • config.redis.cloud_authentication.auth_provider
  • config.redis.cloud_authentication.aws_access_key_id
  • config.redis.cloud_authentication.aws_assume_role_arn
  • config.redis.cloud_authentication.aws_cache_name
  • config.redis.cloud_authentication.aws_region
  • config.redis.cloud_authentication.aws_role_session_name
  • config.redis.cloud_authentication.aws_secret_access_key
  • config.redis.cloud_authentication.azure_client_id
  • config.redis.cloud_authentication.azure_client_secret
  • config.redis.cloud_authentication.azure_tenant_id
  • config.redis.cloud_authentication.gcp_service_account_json
  • config.redis.host
  • config.redis.password
  • config.redis.port
  • config.redis.sentinel_password
  • config.redis.sentinel_username
  • config.redis.server_name
  • config.redis.username
Rate Limiting
(rate-limiting)
  • config.redis.cloud_authentication.auth_provider
  • config.redis.cloud_authentication.aws_access_key_id
  • config.redis.cloud_authentication.aws_assume_role_arn
  • config.redis.cloud_authentication.aws_cache_name
  • config.redis.cloud_authentication.aws_region
  • config.redis.cloud_authentication.aws_role_session_name
  • config.redis.cloud_authentication.aws_secret_access_key
  • config.redis.cloud_authentication.azure_client_id
  • config.redis.cloud_authentication.azure_client_secret
  • config.redis.cloud_authentication.azure_tenant_id
  • config.redis.cloud_authentication.gcp_service_account_json
  • config.redis.host
  • config.redis.password
  • config.redis.port
  • config.redis.server_name
  • config.redis.username
Rate Limiting Advanced
(rate-limiting-advanced)
  • config.redis.cloud_authentication.auth_provider
  • config.redis.cloud_authentication.aws_access_key_id
  • config.redis.cloud_authentication.aws_assume_role_arn
  • config.redis.cloud_authentication.aws_cache_name
  • config.redis.cloud_authentication.aws_region
  • config.redis.cloud_authentication.aws_role_session_name
  • config.redis.cloud_authentication.aws_secret_access_key
  • config.redis.cloud_authentication.azure_client_id
  • config.redis.cloud_authentication.azure_client_secret
  • config.redis.cloud_authentication.azure_tenant_id
  • config.redis.cloud_authentication.gcp_service_account_json
  • config.redis.host
  • config.redis.password
  • config.redis.port
  • config.redis.sentinel_password
  • config.redis.sentinel_username
  • config.redis.server_name
  • config.redis.username
Request Callout
(request-callout)
  • config.cache.redis.cloud_authentication.auth_provider
  • config.cache.redis.cloud_authentication.aws_access_key_id
  • config.cache.redis.cloud_authentication.aws_assume_role_arn
  • config.cache.redis.cloud_authentication.aws_cache_name
  • config.cache.redis.cloud_authentication.aws_region
  • config.cache.redis.cloud_authentication.aws_role_session_name
  • config.cache.redis.cloud_authentication.aws_secret_access_key
  • config.cache.redis.cloud_authentication.azure_client_id
  • config.cache.redis.cloud_authentication.azure_client_secret
  • config.cache.redis.cloud_authentication.azure_tenant_id
  • config.cache.redis.cloud_authentication.gcp_service_account_json
  • config.cache.redis.host
  • config.cache.redis.password
  • config.cache.redis.port
  • config.cache.redis.sentinel_password
  • config.cache.redis.sentinel_username
  • config.cache.redis.server_name
  • config.cache.redis.username
  • config.callouts.request.body.custom
  • config.callouts.request.body.custom.additionalProperties
  • config.callouts.request.headers.custom
  • config.callouts.request.headers.custom.additionalProperties
  • config.callouts.request.http_opts.proxy.auth_password
  • config.callouts.request.http_opts.proxy.auth_username
  • config.callouts.request.query.custom
  • config.callouts.request.query.custom.additionalProperties
  • config.callouts.request.url
  • config.upstream.body.custom
  • config.upstream.body.custom.additionalProperties
  • config.upstream.headers.custom
  • config.upstream.headers.custom.additionalProperties
  • config.upstream.query.custom
  • config.upstream.query.custom.additionalProperties
Request Transformer Advanced
(request-transformer-advanced)
  • config.add.body
  • config.add.headers
  • config.add.querystring
  • config.append.body
  • config.append.headers
  • config.append.querystring
  • config.rename.body
  • config.rename.headers
  • config.rename.querystring
  • config.replace.body
  • config.replace.headers
  • config.replace.querystring
Response Rate Limiting
(response-ratelimiting)
  • config.redis.cloud_authentication.auth_provider
  • config.redis.cloud_authentication.aws_access_key_id
  • config.redis.cloud_authentication.aws_assume_role_arn
  • config.redis.cloud_authentication.aws_cache_name
  • config.redis.cloud_authentication.aws_region
  • config.redis.cloud_authentication.aws_role_session_name
  • config.redis.cloud_authentication.aws_secret_access_key
  • config.redis.cloud_authentication.azure_client_id
  • config.redis.cloud_authentication.azure_client_secret
  • config.redis.cloud_authentication.azure_tenant_id
  • config.redis.cloud_authentication.gcp_service_account_json
  • config.redis.host
  • config.redis.password
  • config.redis.port
  • config.redis.server_name
  • config.redis.username
SAML
(saml)
  • config.idp_certificate
  • config.redis.cloud_authentication.auth_provider
  • config.redis.cloud_authentication.aws_access_key_id
  • config.redis.cloud_authentication.aws_assume_role_arn
  • config.redis.cloud_authentication.aws_cache_name
  • config.redis.cloud_authentication.aws_region
  • config.redis.cloud_authentication.aws_role_session_name
  • config.redis.cloud_authentication.aws_secret_access_key
  • config.redis.cloud_authentication.azure_client_id
  • config.redis.cloud_authentication.azure_client_secret
  • config.redis.cloud_authentication.azure_tenant_id
  • config.redis.cloud_authentication.gcp_service_account_json
  • config.redis.host
  • config.redis.password
  • config.redis.port
  • config.redis.sentinel_password
  • config.redis.sentinel_username
  • config.redis.server_name
  • config.redis.username
  • config.request_signing_certificate
  • config.request_signing_key
  • config.response_encryption_key
  • config.session_secret
Service Protection
(service-protection)
  • config.redis.cloud_authentication.auth_provider
  • config.redis.cloud_authentication.aws_access_key_id
  • config.redis.cloud_authentication.aws_assume_role_arn
  • config.redis.cloud_authentication.aws_cache_name
  • config.redis.cloud_authentication.aws_region
  • config.redis.cloud_authentication.aws_role_session_name
  • config.redis.cloud_authentication.aws_secret_access_key
  • config.redis.cloud_authentication.azure_client_id
  • config.redis.cloud_authentication.azure_client_secret
  • config.redis.cloud_authentication.azure_tenant_id
  • config.redis.cloud_authentication.gcp_service_account_json
  • config.redis.host
  • config.redis.password
  • config.redis.port
  • config.redis.sentinel_password
  • config.redis.sentinel_username
  • config.redis.server_name
  • config.redis.username
Session
(session)
  • config.secret
Solace Consume
(solace-consume)
  • config.flow.properties
  • config.flow.properties.additionalProperties
  • config.session.authentication.access_token
  • config.session.authentication.id_token
  • config.session.authentication.password
  • config.session.authentication.username
  • config.session.host
  • config.session.properties
  • config.session.properties.additionalProperties
Solace Log
(solace-log)
  • config.session.authentication.access_token
  • config.session.authentication.id_token
  • config.session.authentication.password
  • config.session.authentication.username
  • config.session.host
  • config.session.properties
  • config.session.properties.additionalProperties
Solace Upstream
(solace-upstream)
  • config.session.authentication.access_token
  • config.session.authentication.id_token
  • config.session.authentication.password
  • config.session.authentication.username
  • config.session.host
  • config.session.properties
  • config.session.properties.additionalProperties
Standard Webhooks
(standard-webhooks)
  • config.secret_v1
Upstream OAuth
(upstream-oauth)
  • config.cache.redis.cloud_authentication.auth_provider
  • config.cache.redis.cloud_authentication.aws_access_key_id
  • config.cache.redis.cloud_authentication.aws_assume_role_arn
  • config.cache.redis.cloud_authentication.aws_cache_name
  • config.cache.redis.cloud_authentication.aws_region
  • config.cache.redis.cloud_authentication.aws_role_session_name
  • config.cache.redis.cloud_authentication.aws_secret_access_key
  • config.cache.redis.cloud_authentication.azure_client_id
  • config.cache.redis.cloud_authentication.azure_client_secret
  • config.cache.redis.cloud_authentication.azure_tenant_id
  • config.cache.redis.cloud_authentication.gcp_service_account_json
  • config.cache.redis.host
  • config.cache.redis.password
  • config.cache.redis.port
  • config.cache.redis.sentinel_password
  • config.cache.redis.sentinel_username
  • config.cache.redis.server_name
  • config.cache.redis.username
  • config.oauth.client_id
  • config.oauth.client_secret
  • config.oauth.password
  • config.oauth.token_headers
  • config.oauth.token_headers.additionalProperties
  • config.oauth.token_post_args
  • config.oauth.token_post_args.additionalProperties
  • config.oauth.username

Supported Vault backends

Each vault has its own required configuration. You can provide this configuration by creating a Vault entity, or by configuring specific environment variables before starting Kong Gateway.

For more information, choose a Vault below to see the specific configuration required.

Backend Kong Gateway OSS Kong Gateway Enterprise Konnect supported
Environment variable Supported Supported Supported
Konnect (Konnect Config Store) Not supported Not supported Supported
AWS Secrets Manager Not supported Supported Supported
Azure Key Vaults Not supported Supported Supported
Google Cloud Secret Not supported Supported Supported
HashiCorp Vault Not supported Supported Supported
CyberArk Secrets Manager (Conjur) v3.11+ Not supported Supported Supported

How do I reference secrets stored in a Vault?

When you want to use a secret stored in a Vault, you can reference the secret with a vault reference. You can use the vault reference in places such as kong.conf, declarative configuration files, logs, or in the UI.

The Vault backend may store multiple related secrets inside an object, but the reference should always point to a key that resolves to a string value. For example, the following reference:

{vault://hcv/pg/username}

Would point to a secret object called pg inside a HashiCorp Vault, which may return the following value:

{
  "username": "john",
  "password": "doe"
}

Kong Gateway receives the payload and extracts the "username" value of "john" for the secret reference of {vault://hcv/pg/username}.

Vault references must be used for the whole referenced value. Imagine that you’re calling a upstream service with the authentication token ABC123:

Works Configuration Value Vault Value
false Bearer {vault://hcv/myservice-auth-token} ABC123
true {vault://hcv/myservice-auth-token} Bearer ABC123

When using Vault references in plugin configs to add headers, ensure that the secret value stored in your Vault follows the key:value format. The entire header definition, both name and value, needs to be provided by the resolved secret.

Secret rotation in Vaults

By default, Kong Gateway automatically refreshes secrets once every minute in the background. You can also configure how often Kong Gateway refreshes secrets using the Vault entity configuration.

There are two types of refresh configuration available:

  • Refresh periodically using TTLs: For example, check for a new TLS certificate once per day.
  • Refresh on failure: For example, on a database authentication failure, check if the secrets were updated, and try again.

For more information, see Secret management.

Vault provider-specific configuration parameters

When you set up a Vault, each provider has specific parameters that you can or must configure to integrate the Vault with a provider. For the entire Vault configuration schema, see the schema reference.

You can set up a Vault in one of the following ways:

  • Using the Vault entity
  • Using environment variables, set at Kong Gateway startup
  • Using parameters in kong.conf, set at Kong Gateway startup

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.

Field name

Parameter format

Description
Environment Variable Prefix
  • Vault entity: vaults.config.prefix
  • kong.conf parameter: vault_env_prefix
  • Environment variable: KONG_VAULT_ENV_PREFIX
The prefix for the environment variable that the value will be stored in.
Base64 Decode
v3.11+
  • Vault entity: vaults.config.base64_decode
  • kong.conf parameter: vault_env_base64_decode
  • Environment variable: KONG_VAULT_ENV_BASE64_DECODE
Decode all secrets in this vault as base64. Useful for binary data. If some of the secrets in the vault are not base64-encoded, an error will occur when using them. We recommend creating a separate vault for base64 secrets.

AWS Secrets Manager credentials

To access secrets stored in the AWS Secrets Manager, Kong Gateway needs to be configured with an IAM Role that has sufficient permissions to read the required secret values.

Kong Gateway can automatically fetch IAM role credentials based on your AWS environment, observing the following precedence order:

  • Fetch from credentials defined in environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.
  • Fetch from profile and credential file, defined by AWS_PROFILE and AWS_SHARED_CREDENTIALS_FILE.
  • Fetch from an ECS container credential provider.
  • Fetch from an EKS IAM roles for service account.
  • Fetch from EC2 IMDS metadata. Both v1 and v2 are supported

Kong Gateway also supports role assuming (with vaults.config.assume_role_arn and vaults.config.role_session_name) which allows you to use a different IAM role to fetch secrets from AWS Secrets Manager. This is a common practice in permission division and governance and cross-AWS account management.

Note: IAM Identity Center credential provider and process credential provider are not supported.

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

Store values as secrets

You can set up a Vault in one of the following ways.

Set up a Vault entity

kong.yaml
_format_version: "3.0"
vaults:
  - name: env
    description: ENV vault for secrets
    prefix: my-env-vault
    config:
      prefix: MY_SECRET_

Store secrets as environment variables

You can store secrets as environment variables instead of configuring a Vault entity or third-party backend vault.

Use case

Environment variable example

Secret reference example
Single secret value export MY_SECRET_VALUE=example-secret {vault://env/my-secret-value}
Multiple secrets (flat JSON string) export PG_CREDS='{"username":"user", "password":"pass"}' {vault://env/pg-creds/username}

{vault://env/pg-creds/password}

Schema

FAQs

What types of fields can be used in Vaults?

Vaults work with “referenceable” fields. All fields in kong.conf are referenceable and some fields within entities (for example, plugins, certificates) are also. Refer to the appropriate entity documentation to learn more.

Can Vaults be referenced during custom plugin development?

Yes. The plugin development kit (PDK) offers a Vaults module (kong.vault) that can be used to resolve, parse, and verify Vault references.

What data types can I use when referencing a secret in a Vault?

A secret reference points to a string value. No other data types are currently supported.

I have a secret with multiple versions, how do I specify an earlier version when I’m referencing the secret?

If you have a secret with multiple versions, you can access the current version or any previous version of the secret by specifying a version in the reference.

In the following AWS example, AWSCURRENT refers to the latest secret version and AWSPREVIOUS refers to an older version:

# For AWSCURRENT, not specifying version
{vault://aws/secret-name/foo}

# For AWSCURRENT, specifying version == 1
{vault://aws/secret-name/foo#1}

# For AWSPREVIOUS, specifying version == 2
{vault://aws/secret-name/foo#2}

This applies to all providers with versioned secrets.

My secret in AWS Secret Manager has a / backslash in the secret name. How do I reference this secret in Kong Gateway?

The slash symbol (/) is a valid character for the secret name in AWS Secrets Manager. If you want to reference a secret name that starts with a slash or has two consecutive slashes, transform one of the slashes in the name into URL-encoded format. For example:

  • A secret named /secret/key should be referenced as {vault://aws/%2Fsecret/key}
  • A secret named secret/path//aaa/key should be referenced as {vault://aws/secret/path/%2Faaa/key}

Since Kong Gateway tries to resolve the secret reference as a valid URL, using a slash instead of a URL-encoded slash will result in unexpected secret name fetching.

I have secrets stored in multiple AWS Secret Manager regions, how do I reference those secrets in Kong Gateway?

You can create multiple Vault entities, one per region with the config.region parameter. You’d then reference the secret by the name of the Vault:

{vault://aws-eu-central-vault/secret-name/foo}
{vault://aws-us-west-vault/secret-name/snip}

I’m using Google Workload Identity, how do I configure a Vault?

To use GCP Secret Manager with Workload Identity on a GKE cluster, update your pod spec so that the service account (GCP_SERVICE_ACCOUNT) is attached to the pod. For configuration information, read the Workload Identity configuration documentation.

Notes:

  • With Workload Identity, setting the GCP_SERVICE_ACCOUNT isn’t necessary.
  • When using GCP Vault as a backend, make sure you have configured system as part of the lua_ssl_trusted_certificate configuration directive so that the SSL certificates used by the official GCP API can be trusted by Kong Gateway.

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.
  • v3.14+ If you’re using the gcp_iam auth method, Kong Gateway generates a signed JWT using the GCP service account configured in config.gcp_service_account and exchanges it for a HashiCorp Vault token via the GCP login path (config.gcp_login_path). The role is specified by config.gcp_auth_role.
  • v3.14+ If you’re using the gcp_gce (GCP Compute Engine) auth method, Kong Gateway uses the instance identity token from the GCE metadata server and exchanges it for a HashiCorp Vault token via the GCP login path (config.gcp_login_path). The role is specified by config.gcp_auth_role.
  • v3.14+ If you’re using the azure auth method, Kong Gateway uses the Azure Managed Identity token and exchanges it for a HashiCorp Vault token via the Azure login path (config.azure_login_path). The role is specified by config.azure_auth_role.
  • v3.14+ If you’re using the aws_ec2 auth method, Kong Gateway uses the EC2 instance identity document and a nonce (config.aws_auth_nonce) to authenticate with HashiCorp Vault via the AWS login path (config.aws_login_path). The role is specified by config.aws_auth_role.
  • v3.14+ If you’re using the aws_iam auth method, Kong Gateway signs an AWS STS GetCallerIdentity request using IAM credentials (config.aws_access_key_id and config.aws_secret_access_key, or the default credential provider chain) and exchanges it for a HashiCorp Vault token via the AWS login path (config.aws_login_path). The role is specified by config.aws_auth_role. For cross-account authentication, config.aws_assume_role_arn and config.aws_role_session_name are required to assume an IAM role in the target account before signing the request.

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.

Can Azure Key Vault be used with a proxy?

v3.12+ Yes. Azure Key Vault supports proxy configuration using either environment variables or client constructor arguments.

Environment variables

export AZURE_HTTP_PROXY=http://proxy.example.com:8080
export AZURE_HTTPS_PROXY=http://proxy.example.com:8080
export AZURE_NO_PROXY=localhost,127.0.0.1,.local
export AZURE_AUTH_USERNAME=proxyuser
export AZURE_AUTH_PASSWORD=proxypass

Constructor arguments

local azure_client = require("resty.azure"):new({
  tenant_id = "tenant-uuid",
  client_id = "app-registration-client-id",
  client_secret = "app-registration-client-secret",
  http_proxy = "http://proxy.example.com:8080",
  https_proxy = "http://proxy.example.com:8080",
  no_proxy = "localhost,127.0.0.1,.local",
  auth_username = "proxyuser",
  auth_password = "proxypass",
})

Notes:

  • Constructor arguments take precedence over environment variables.
  • When auth_username and auth_password are provided, they will be automatically converted to a Basic authentication header for both HTTP and HTTPS proxy authorization.

Next Steps

Set up a Konnect Config Store
Set up HashiCorp Vault as a vault backend
Keyring
Something wrong?
Report an Issue | Edit this Page
View all Kong documentation

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 Slack Community
Contact Support