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}.

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.

Limitation: Kong Gateway doesn’t currently support storing certificate key content into vaults or environment variables for kong.conf settings that use file paths. For example, ssl_cert_key configures a certificate key file path which can’t be stored as a reference.

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
ACMEaccount_email eab_kid eab_hmac_key
AWS Lambdaaws_key aws_secret aws_assume_role_arn
Azure Functionsapikey clientid
Forward Proxy Advancedauth_username auth_password
GraphQL Rate Limiting Advancedredis.username redis.password redis.sentinel_username redis.sentinel_password
Kafka Logauthentication.user authentication.password
Kafka Upstreamauthentication.user authentication.password
LDAP Authentication Advancedldap_password bind_dn
Logglykey
OpenID Connectclient_id client_secret session_secret session_redis_username session_redis_password
OpenTelemetryheaders
Proxy Caching Advancedredis.password redis.sentinel_username redis.sentinel_password
Rate Limitingredis_username redis_password
Rate Limiting Advancedredis.username redis.password redis.sentinel_username redis.sentinel_password
Request Transformer Advancedreplace.headers replace.querystring replace.body rename.headers rename.querystring rename.body add.headers add.querystring add.body append.headers append.querystring append.body
Response Rate Limitingredis_username redis_password
SAMLidp_certificate encryption_key request_signing_key request_signing_certificate session_secret session_redis_username session_redis_password
Sessionsecret
Vault Authenticationvaults.vault_token vault_credentials.secret_token

Supported backends

Kong Gateway supports the following vault backends:

  • Environment variables
  • AWS Secrets Manager
  • GCP Secrets Manager
  • HashiCorp Vault

See the backends overview for more information about each option.

Get started

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