Skip to content
2023 API Summit Hackathon: Experiment with AI for APIs (August 28 - September 27) Learn More →
Kong Logo | Kong Docs Logo
search
  • We're Hiring!
  • Docs
    • Kong Gateway
      Lightweight, fast, and flexible cloud-native API gateway
      Kong Konnect
      Single platform for SaaS end-to-end connectivity
      Kong Mesh
      Enterprise service mesh based on Kuma and Envoy
      decK
      Helps manage Kong’s configuration in a declarative fashion
      Kong Ingress Controller
      Works inside a Kubernetes cluster and configures Kong to proxy traffic
      Kong Gateway Operator
      Manage your Kong deployments on Kubernetes using YAML Manifests
      Insomnia
      Collaborative API development platform
      Kuma
      Open-source distributed control plane with a bundled Envoy Proxy integration
  • API Specs
  • Plugin Hub
    • Explore the Plugin Hub
      View all plugins View all plugins View all plugins arrow image
    • Functionality View all View all arrow image
      View all plugins
      Authentication's icon
      Authentication
      Protect your services with an authentication layer
      Security's icon
      Security
      Protect your services with additional security layer
      Traffic Control's icon
      Traffic Control
      Manage, throttle and restrict inbound and outbound API traffic
      Serverless's icon
      Serverless
      Invoke serverless functions in combination with other plugins
      Analytics & Monitoring's icon
      Analytics & Monitoring
      Visualize, inspect and monitor APIs and microservices traffic
      Transformations's icon
      Transformations
      Transform request and responses on the fly on Kong
      Logging's icon
      Logging
      Log request and response data using the best transport for your infrastructure
  • Support
  • Community
  • Kong Academy
Get a Demo Start Free Trial
Kong Gateway
3.0.x
  • Home icon
  • Kong Gateway
  • Kong Enterprise
  • Secrets Management
  • Secrets Management
github-edit-pageEdit this page
report-issueReport an issue
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Plugin Hub
  • decK
  • Kong Ingress Controller
  • Kong Gateway Operator
  • Insomnia
  • Kuma

  • Docs contribution guidelines
  • 3.4.x (latest)
  • 3.3.x
  • 3.2.x
  • 3.1.x
  • 3.0.x
  • 2.8.x
  • 2.7.x
  • 2.6.x
  • Archive (pre-2.6)
enterprise-switcher-icon Switch to OSS
On this pageOn this page
  • Referenceable values
  • What can be stored as a secret?
    • Referenceable plugin fields
  • Supported backends
  • Get started
You are browsing documentation for an outdated 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:

{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:

{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 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:

{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:

Plugin Referenceable fields
ACME config.account_email config.eab_kid config.eab_hmac_key config.storage_config.redis.auth config.storage_config.consul.token config.storage_config.vault.token
AWS Lambda config.aws_key config.aws_secret config.aws_assume_role_arn
Azure Functions config.apikey config.clientid
Forward Proxy Advanced config.auth_username config.auth_password
GraphQL Rate Limiting Advanced config.redis.username config.redis.password config.redis.sentinel_username config.redis.sentinel_password
Kafka Log config.authentication.user config.authentication.password
Kafka Upstream config.authentication.user config.authentication.password
LDAP Authentication Advanced config.ldap_password config.bind_dn
Loggly config.key
OpenID Connect config.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.session_secret config.session_redis_username config.session_redis_password
Proxy Caching Advanced config.redis.username config.redis.password config.redis.sentinel_username config.redis.sentinel_password
Rate Limiting config.redis_password config.redis_username
Rate Limiting Advanced config.redis.username config.redis.password config.redis.sentinel_username config.redis.sentinel_password
Response Rate Limiting config.redis_password config.redis_username
Session config.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 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:

  • Get started with secrets management
  • Secrets rotation
  • Backends overview
  • Reference format
  • Advanced usage
Thank you for your feedback.
Was this page useful?
Too much on your plate? close cta icon
More features, less infrastructure with Kong Konnect. 1M requests per month for free.
Try it for Free
  • Kong
    THE CLOUD CONNECTIVITY COMPANY

    Kong powers reliable digital connections across APIs, hybrid and multi-cloud environments.

    • Company
    • Customers
    • Events
    • Investors
    • Careers Hiring!
    • Partners
    • Press
    • Contact
  • Products
    • Kong Konnect
    • Kong Gateway
    • Kong Mesh
    • Get Started
    • Pricing
  • Resources
    • eBooks
    • Webinars
    • Briefs
    • Blog
    • API Gateway
    • Microservices
  • Open Source
    • Install Kong Gateway
    • Kong Community
    • Kubernetes Ingress
    • Kuma
    • Insomnia
  • Solutions
    • Decentralize
    • Secure & Govern
    • Create a Dev Platform
    • API Gateway
    • Kubernetes
    • Service Mesh
Star
  • Terms•Privacy
© Kong Inc. 2023