Secrets management

What is secrets management?

A secret is any sensitive piece of information required for API gateway operations.

Secrets can be information like the following:

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

By storing these values as secrets, you ensure that they aren’t visible in plain text in logs, the UI, kong.conf, or decK files. Once a secret is stored, you can use the secret reference instead of the sensitive information. For example, a secret stored in an environment variable called MY_SECRET_POSTGRES_PASSWORD would be referenced with {vault://env/my-secret-postgres-password}.

You can reference secrets in the following Kong Gateway configuration:

• Any field in the kong.conf
• Referenceable fields in Kong plugins
• Configuration associated with APIs serviced by Kong Gateway

How can I manage secrets in Kong Gateway?

Secret management options vary depending on which Kong Gateway tier you have. Kong Gateway OSS users can only manage secrets by storing them in environment variables. Kong Gateway Enterprise users can use environment variables as well as Vaults. The Vaults entity allows you to store and reference secrets from an external, third-party vault or Konnect Config Store.

Secret rotation is a process that periodically updates secrets. Secret rotation is important for the following reasons:

• Reducing the 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

If you have secrets rotation configured in your third-party vault settings, Kong Gateway can retrieve rotated secrets on a schedule. Kong Gateway can be configured to check for rotated secrets in the following ways:

• Check periodically using TTLs (for example, check for new TLS certificates once per day). This can be configured in the Vault entity configuration.
• Check on failure (for example, on database authentication failure, check if the secrets were updated, and try again). You must write code in Kong Gateway to configure this, so support is limited to PostgreSQL credentials for now.

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.

• Block unauthorized requests in Kong Gateway with the OPA pluginView →
• Collect Konnect audit logsView →
• Collect Dev Portal audit logsView →
• Configure AWS Secrets Manager as a vault backendView →
• Configure CyberArk Conjur as a vault backendView →
• View More →