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
      Insomnia
      Collaborative API development platform
      Kuma
      Open-source distributed control plane with a bundled Envoy Proxy integration
      Docs Contribution Guidelines
      Want to help out, or found an issue in the docs and want to let us know?
  • 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.4.x (latest)
  • Home icon
  • Kong Gateway
  • Kong Enterprise
  • Secrets Management
  • Secrets Rotation
github-edit-pageEdit this page
report-issueReport an issue
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Plugin Hub
  • decK
  • Kong Ingress Controller
  • 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
  • Periodically rotating secrets using TTLs
    • Configuring AWS Secrets Manager Secrets Rotation using TTLs
    • Configuring GCP Secrets Manager Secrets Rotation using TTLs
    • Configuring HashiCorp Vault Secrets Rotation using TTLs

Secrets Rotation

Secrets rotation is a process of updating secrets. Regular rotations of secrets is considered a good practice. Here are some reasons why secrets rotation is important:

  • Reducing impact of compromised secrets
  • Enhancing resilience against brute-force attacks
  • Complying with security regulations
  • Maintaining separation of duties
  • Adapting to evolving threats
  • Mitigating the effects of insider threats

Kong needs to hold many types of secrets to be able to process requests, and to integrate with other systems and clients:

  • TLS certificates
  • Credentials and API keys (to access databases, identity providers, and other services)
  • Cryptographic keys (digital signing and encryption)

There are two main ways to rotate secrets:

  • Rotate periodically using TTLs (e.g. check for new TLS certificate once per day)
  • Rotate on failure (e.g. on database authentication failure, check if the secrets were updated, and try again)

Kong supports both methods for rotating secrets. Rotation on failure requires code to be written, and thus it has limited support in Kong (Postgres credentials for now). There is an experimental Kong PDK API that can be used to rotate secrets on failure: kong.vault.try.

Periodically rotating secrets using TTLs

Kong automatically rotates secrets once every minute in the background. This decouples the secret rotation process from proxying. It has the following consequences:

  • The once-per-minute refresh rate means that a secret with a TTL of 30 seconds might take up to 60 seconds to refresh in the least favorable scenario.
  • Additionally, if the sum of TTL and resurrect_ttl is less than 60 seconds for a given secret, it won’t be refreshed or resurrected correctly.

The TTL based rotation works with most of the Kong supported vaults, including:

  • AWS Secrets Manager
  • GCP Secrets Manager
  • HashiCorp Vault

When rotating with TTLs, it is usually useful to have two versions of the same secret valid at the same time. This means that following steps occur during secrets rotation:

  1. A new secret (or secret version) is created, resulting in three valid ones.
  2. All the three secrets are verified that they work.
  3. The oldest secret (or secret version) is removed/revoked or made otherwise invalid, resulting in two valid ones.

Configuring AWS Secrets Manager Secrets Rotation using TTLs

The default AWS Secrets Manager vault TTLs can be configured through kong.conf or environment variables (the values are in seconds):

KONG_VAULT_AWS_TTL=300
KONG_VAULT_AWS_NEG_TTL=60
KONG_VAULT_AWS_RESURRECT_TTL=300

All AWS secret references will inherit these settings by default, e.g.:

{vault://aws/my-secret-name/foo}

You can override or set the TTLs directly with the references too:

{vault://aws/my-secret-name/foo?ttl=600&neg_ttl=30&resurrect_ttl=600}

You can also create multiple vaults for different types of secrets, and set the TTLs by secret types, e.g.:

curl -i -X PUT http://HOSTNAME:8001/vaults/aws-certs  \
  --data name=aws \
  --data description="Storing secrets in AWS Secrets Manager" \
  --data config.region="us-east-1" \
  --data config.ttl=21600

Now when using certificates you can reference them with:

{vault://aws-certs/certs/web-site}

The secrets (certificates, in this case) referenced with aws-certs vault will share the same 6 hours TTL, and will be rotated one minute earlier than their expiry.

Configuring GCP Secrets Manager Secrets Rotation using TTLs

The default GCP Secrets Manager vault TTLs can be configured through kong.conf or environment variables (the values are in seconds):

KONG_VAULT_GCP_TTL=300
KONG_VAULT_GCP_NEG_TTL=60
KONG_VAULT_GCP_RESURRECT_TTL=300

All GCP secret references will inherit these settings by default, e.g.:

{vault://gcp/my-secret-name/foo}

You can override or set the TTLs directly with the references too:

{vault://gcp/my-secret-name/foo?ttl=600&neg_ttl=30&resurrect_ttl=600}

You can also create multiple vaults for different types of secrets, and set the TTLs by secret types, e.g.:

curl -i -X PUT http://HOSTNAME:8001/vaults/gcp-certs  \
  --data name=gcp \
  --data description="Storing secrets in GCP Secrets Manager" \
  --data config.project_id="my_project_id-1" \
  --data config.ttl=21600

Now when using certificates you can reference them with:

{vault://gcp-certs/certs/web-site}

The secrets (certificates, in this case) referenced with gcp-certs vault will share the same 6 hours TTL, and will be rotated one minute earlier than their expiry.

Configuring HashiCorp Vault Secrets Rotation using TTLs

The default HashiCorp Vault TTLs can be configured through kong.conf or environment variables (the values are in seconds):

KONG_VAULT_HCV_TTL=300
KONG_VAULT_HCV_NEG_TTL=60
KONG_VAULT_HCV_RESURRECT_TTL=300

All HCV secret references will inherit these settings by default, e.g.:

{vault://hcv/my-secret-name/foo}

You can override or set the TTLs directly with the references too:

{vault://hcv/my-secret-name/foo?ttl=600&neg_ttl=30&resurrect_ttl=600}

You can also create multiple vaults for different types of secrets, and set the TTLs by secret types, e.g.:

curl -i -X PUT http://HOSTNAME:8001/vaults/hcv-certs  \
  --data name=hcv \
  --data description="Storing secrets in HashiCorp Vault" \
  --data config.token="<my-token>" \
  --data config.ttl=21600

Now you can reference certificates with:

{vault://hcv-certs/certs/web-site}

The secrets (certificates, in this case) referenced with hcv-certs vault will share the same 6 hours TTL, and will be rotated one minute earlier than their expiry.

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