You are browsing documentation for an older version. See the latest documentation here.

Secrets Management

A secret is any sensitive piece of information required for API gateway operations. Secrets may be part of the core Kong Gateway configuration, they may be used in plugins, or they might be part of configuration associated with APIs serviced by the gateway.

Some of the most common types of secrets used by Kong Gateway include:

  • Data store usernames and passwords, used with PostgreSQL and Redis
  • Private X.509 certificates
  • API keys
  • Sensitive plugin configuration fields, generally used for authentication, hashing, signing, or encryption.

Kong Gateway lets you store certain values in a vault. By storing sensitive values as secrets, you ensure that they are not visible in plaintext throughout the platform, in places such as kong.conf, in declarative configuration files, logs, or in the Kong Manager UI. Instead, you can reference each secret with a vault reference.

For example, the following reference resolves to the environment variable MY_SECRET_POSTGRES_PASSWORD:

  1. {vault://env/my-secret-postgres-password}

In this way, secrets management becomes centralized.

Referenceable values

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

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:

  1. {vault://hcv/pg/username}

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

  1. {
  2. "username": "john",
  3. "password": "doe"
  4. }

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

If you have a single value secret with identifier pg/username, you need to add / as a suffix to a reference so that it is properly sent to the vault API:

  1. {vault://hcv/pg/username/}

What can be stored as a secret?

Most of the Kong configuration values can be stored as a secret, such as pg_user and pg_password.

You can even store the default certificates in vaults, e.g.:

  1. SSL_CERT=$(cat cluster.crt) \
  2. SSL_CERT_KEY=$(cat cluster.key) \
  3. KONG_SSL_CERT={vault://env/ssl-cert} \
  4. KONG_SSL_CERT_KEY={vault://env/ssl-cert-key} \
  5. kong prepare

The Kong license, usually configured with a KONG_LICENSE_DATA environment variable, can be stored as a secret.

The Kong Admin API certificate object can be stored as a secret.

Referenceable plugin fields

Some plugins have fields that can be stored as secrets in a vault backend. These fields are labelled as referenceable.

The following plugins support vault references for specific fields. See each plugin’s documentation for more information on each field:

PluginReferenceable fields
ACMEconfig.account_email config.eab_kid config.eab_hmac_key config.storage_config.redis.username config.storage_config.redis.password config.storage_config.consul.token config.storage_config.vault.token
AI Proxyconfig.auth.header_name config.auth.header_value config.auth.param_name config.auth.param_value
AI Request Transformerconfig.llm.auth.header_name config.llm.auth.header_value config.llm.auth.param_name config.llm.auth.param_value
AI Response Transformerconfig.llm.auth.header_name config.llm.auth.header_value config.llm.auth.param_name config.llm.auth.param_value
AWS Lambdaconfig.aws_key config.aws_secret config.aws_assume_role_arn
Azure Functionsconfig.apikey config.clientid
Datadogconfig.host
Forward Proxy Advancedconfig.auth_username config.auth_password
GraphQL Rate Limiting Advancedconfig.redis.username config.redis.password config.redis.sentinel_username config.redis.sentinel_password
HTTP Logconfig.http_endpoint config.headers
Kafka Logconfig.authentication.user config.authentication.password
Kafka Upstreamconfig.authentication.user config.authentication.password
LDAP Authentication Advancedconfig.ldap_password config.bind_dn
Logglyconfig.key
OAuth 2.0 Introspectionconfig.authorization_value
OpenID Connectconfig.client_id config.client_secret config.client_jwk.k config.client_jwk.d config.client_jwk.p config.client_jwk.q config.client_jwk.dp config.client_jwk.dq config.client_jwk.qi config.client_jwk.oth config.client_jwk.r config.client_jwk.t config.login_redirect_uri config.logout_redirect_uri config.scopes config.introspection_headers_values config.session_secret config.session_redis_username config.session_redis_password
OpenTelemetryconfig.endpoint config.headers
Proxy Caching Advancedconfig.redis.username config.redis.password config.redis.sentinel_username config.redis.sentinel_password
Rate Limitingconfig.redis.username config.redis.password
Rate Limiting Advancedconfig.redis.username config.redis.password config.redis.sentinel_username config.redis.sentinel_password
Request Transformer Advancedconfig.rename.body config.rename.headers config.rename.querystring config.replace.body config.replace.headers config.replace.querystring config.add.body config.add.headers config.add.querystring config.append.body config.append.headers config.append.querystring
Response Rate Limitingconfig.redis.username config.redis.password
SAMLconfig.idp_certificate config.response_encryption_key config.request_signing_key config.request_signing_certificate config.session_secret config.session_redis_username config.session_redis_password
Sessionconfig.secret

Note: The Vault plugin interacts with the vaults and vault_credentials entities. For these entities, the vaults.vault_token and vault_credentials.secret_token parameters are referenceable.

Supported backends

Kong Gateway supports the following vault backends:

  • Environment variables
  • AWS Secrets Manager
  • GCP Secret Manager
  • Azure Key Vaults
  • HashiCorp Vault

See the backends overview for more information about each option.

Get started

For further information on secrets management, see the following topics: