Configure AWS Secrets Manager as a vault backend

Uses: Kong Gateway decK

Deployment Platform:

Prerequisites

AWS configuration

This tutorial requires at least one secret in AWS Secrets Manager. In this example, the secret is named my-aws-secret and contains a key/value pair in which the key is token.

You will also need the following authentication information to connect your AWS Secrets Manager with Kong Gateway Enterprise:

Your access key ID
Your secret access key
Your session token
Your AWS region, us-east-1 in this example

export AWS_ACCESS_KEY_ID='YOUR AWS ACCESS KEY ID'
export AWS_SECRET_ACCESS_KEY='YOUR AWS SECRET ACCESS KEY'

If you get an error stating “The security token included in the request is invalid”, you need to set the AWS_SESSION_TOKEN environment variable.

Note that these variables need to be passed when creating your Data Plane container.

Alternative connection methods such as assume role and how to use an aws_session_token can be found on the AWS Secrets Manager page

Kong Konnect

This is a Konnect tutorial. If you don’t have a Konnect account, you can get started quickly with our onboarding wizard.

The following Konnect items are required to complete this tutorial:
- Personal access token (PAT): Create a new personal access token by opening the Konnect PAT page and selecting Generate Token.
- Control Plane Name: You can use an existing Control Plane or create a new one to use for this tutorial.
- Konnect Proxy URL: By default, a self-hosted Data Plane uses http://localhost:8000. You can set up Data Plane nodes for your Control Plane from the Gateway Manager in Konnect.

Set the personal access token, the Control Plane name, the Control Plane URL, and the Konnect proxy URL as environment variables:

 export DECK_KONNECT_TOKEN='YOUR KONNECT TOKEN'
 export DECK_KONNECT_CONTROL_PLANE_NAME='YOUR CONTROL PLANE NAME'
 export KONNECT_CONTROL_PLANE_URL=https://us.api.konghq.com
 export KONNECT_PROXY_URL='KONNECT PROXY URL'

Kong Gateway running

This tutorial requires Kong Gateway Enterprise. If you don’t have Kong Gateway set up yet, you can use the quickstart script with an enterprise license to get an instance of Kong Gateway running almost instantly.

Export your license to an environment variable:

 export KONG_LICENSE_DATA='LICENSE-CONTENTS-GO-HERE'

Run the quickstart script:

 curl -Ls https://get.konghq.com/quickstart | bash -s -- -e KONG_LICENSE_DATA \
      -e AWS_ACCESS_KEY_ID \
      -e AWS_SECRET_ACCESS_KEY \
      -e AWS_SESSION_TOKEN

Once Kong Gateway is ready, you will see the following message:

 Kong Gateway Ready

decK

decK is a CLI tool for managing Kong Gateway declaratively with state files. To complete this tutorial you will first need to install decK.

Configure the Vault entity

Using decK, create a Vault entity with the required parameters for AWS:

echo '
_format_version: "3.0"
vaults:
  - name: aws
    prefix: aws-vault
    description: Storing secrets in AWS Secrets Manager
    config:
      region: us-east-1
' | deck gateway apply -

Validate

To validate that the secret was stored correctly in AWS you can use the kong vault get command within the Data Plane container.

 kong vault get {vault://aws-vault/my-aws-secret/token}

 kong vault get {vault://aws-vault/my-aws-secret/token}

If the vault was configured correctly, this command should return the value of the secret. Then, you can use {vault://aws-vault/my-aws-secret/token} to reference the secret in any referenceable field.

Cleanup

Clean up AWS resources

If you created new AWS resources for this tutorial, make sure to delete them to avoid unnecessary charges.

Clean up Konnect environment

If you created a new control plane and want to conserve your free trial credits or avoid unnecessary charges, delete the new control plane used in this tutorial.

Destroy the Kong Gateway container

curl -Ls https://get.konghq.com/quickstart | bash -s -- -d

FAQs

How do I rotate my secrets in AWS Secrets Manager and how does Kong Gateway pick up the new secret values?

You can rotate your secret in AWS Secrets Manager by creating a new secret version with the updated value. You’ll also want to configure the ttl settings in your Kong Gateway Vault entity so that Kong Gateway pulls the rotated secret periodically.

My secret in AWS Secret Manager has a / backslash in the secret name. How do I reference this secret in Kong Gateway?

The slash symbol (/) is a valid character for the secret name in AWS Secrets Manager. If you want to reference a secret name that starts with a slash or has two consecutive slashes, transform one of the slashes in the name into URL-encoded format. For example:

A secret named /secret/key should be referenced as {vault://aws/%2Fsecret/key}
A secret named secret/path//aaa/key should be referenced as {vault://aws/secret/path/%2Faaa/key}

Since Kong Gateway tries to resolve the secret reference as a valid URL, using a slash instead of a URL-encoded slash will result in unexpected secret name fetching.

I have secrets stored in multiple AWS Secret Manager regions, how do I reference those secrets in Kong Gateway?

You can create multiple Vault entities, one per region with the config.region parameter. You’d then reference the secret by the name of the Vault:

{vault://aws-eu-central-vault/secret-name/foo}
{vault://aws-us-west-vault/secret-name/snip}

Next Steps

Review the Vaults entity